# Webhooks The webhook endpoint is the main way to send data into Zaphiri from external services. Each [[API-Reference/Integrations|integration]] has a unique token that acts as the URL identifier. No JWT authentication is needed: the token in the URL authenticates the request. > [!quote] Any source, one Inbox > If your tool can send an HTTP POST with JSON, it can add to your Zaphiri Inbox. --- ## Receive Webhook Accepts incoming data and creates inbox items for the authenticated integration. Items land in the account's Inbox as pending, and can be converted to Zaphiri tasks by hand or automatically. ``` POST /api/v1/inbox/{token} ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `token` | string | The integration's 64-character webhook token | ### Headers | Header | Required | Value | |--------|----------|-------| | `Content-Type` | **Yes** | `application/json` | > [!warning] Content-Type required > The webhook endpoint strictly enforces `application/json`. Requests with any other Content-Type (including no Content-Type) return `415 Unsupported Media Type`. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `title` | string | No | Optional title applied to all items in this batch | | `items` | array | **Yes** | Array of item objects (1–50 items) | | `metadata` | object | No | Arbitrary JSON metadata stored with each item | | `overrides` | object | No | Per-request overrides for the integration's template config | ### Item Object | Field | Type | Required | Description | |-------|------|----------|-------------| | `text` | string | **Yes** | The item content (max 10,000 characters) | | `source` | string | No | Identifier for the originating service (for example `"github"`, `"todoist"`) | | `location` | integer | No | Optional sort/position hint | | `external_id` | string | No | Unique ID from the source system, used for deduplication | ### Overrides Object Overrides let you change the integration's default template values for a specific request. Any field not included in `overrides` falls back to the integration's template config. | Field | Type | Description | |-------|------|-------------| | `label` | string | Override the default label | | `project` | string | Override the default project | | `estimated_minutes` | integer | Override the default time estimate | | `energy` | string | Override energy level: `"low"`, `"medium"`, `"high"` | | `priority` | string | Override priority: `"low"`, `"medium"`, `"high"`, `"urgent"` | | `date` | string | Explicit date in `YYYY-MM-DD` format (overrides `date_mode`) | --- ## Examples ### Minimal Request The simplest possible webhook, a single item with just text: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/{token} \ -H "Content-Type: application/json" \ -d '{ "items": [ {"text": "Review the Q4 budget report"} ] }' ``` ### Multi-Item Batch Send several items in a single request: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/{token} \ -H "Content-Type: application/json" \ -d '{ "title": "Sprint Backlog Import", "items": [ {"text": "Fix login redirect bug", "source": "jira", "external_id": "PROJ-142"}, {"text": "Add password reset flow", "source": "jira", "external_id": "PROJ-143"}, {"text": "Update API rate limit docs", "source": "jira", "external_id": "PROJ-144"} ] }' ``` ### With Overrides Override the integration's default template values for a specific request: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/{token} \ -H "Content-Type: application/json" \ -d '{ "items": [ {"text": "Urgent production fix needed", "source": "pagerduty"} ], "overrides": { "priority": "urgent", "energy": "high", "date": "2026-02-18" } }' ``` ### With Metadata Attach arbitrary JSON metadata to items for later reference: ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/{token} \ -H "Content-Type: application/json" \ -d '{ "items": [ {"text": "Deploy v2.4.1 to staging", "source": "ci"} ], "metadata": { "build_id": "abc123", "commit_sha": "9f3a2b1", "branch": "release/2.4.1" } }' ``` --- ## Response ### Success `200 OK` ```json { "status": "accepted", "items_received": 3, "items_deduplicated": 1 } ``` > [!note] Task ID > The `task_id` field is only included when auto-convert creates a task. | Field | Type | Description | |-------|------|-------------| | `status` | string | Always `"accepted"` on success | | `items_received` | integer | Total number of items in the request | | `items_deduplicated` | integer | Number of items skipped due to duplicate `external_id` | | `task_id` | string | Zaphiri task ID if auto-convert was triggered (only present when auto-convert creates a task) | > [!tip] Check deduplication counts > If `items_deduplicated` is unexpectedly high, check that your external IDs are unique across requests. The API deduplicates within the same integration, so items with the same `external_id` are only stored once. --- ## Deduplication The API automatically deduplicates items by `external_id` within each integration. This means: - If you send an item with `external_id: "PROJ-142"` and that ID already exists for this integration, the item is silently skipped - Deduplication also applies **within a single batch**. If two items in the same request have the same `external_id`, only the first is stored - Items without an `external_id` are never deduplicated > [!success] Safe to retry > Because of deduplication, it's safe to retry failed webhook deliveries without creating duplicate Inbox items. Make sure you include consistent `external_id` values. --- ## Auto-Convert If the integration's template config has `auto_convert: true`, items skip the Inbox and are converted into Zaphiri tasks straight away. ### Individual Tasks By default, each item becomes a separate Zaphiri task. The task uses the item's text as the title (truncated to 100 characters if needed) and inherits all resolved template values (date, label, priority, energy, etc.). ### Grouped Tasks When `group_items: true` is also enabled, all items in a single webhook request are combined into **one Zaphiri task**: - The task title uses `group_title_template` (or falls back to the integration name) - All items are rendered as a list in the task body - Template variables are available: `{{date}}`, `{{count}}`, `{{source}}` - The `list_style` setting controls whether items render as bullets or checkboxes **Example template**: `"Todoist Import - {{date}} ({{count}} items)"` The response includes the created `task_id`: ```json { "status": "accepted", "items_received": 5, "items_deduplicated": 0, "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` --- ## Error Responses ### Invalid Token `401` ```json { "error": "invalid_token" } ``` The token does not match any active integration, or the integration has been deactivated. ### Wrong Content Type `415` ```json { "error": "content_type_must_be_application_json" } ``` ### Payload Too Large `413` ```json { "error": "payload_too_large" } ``` Request body exceeds 1 MB. ### Validation Failed `422` ```json { "error": "validation_failed", "details": "items array is required and must not be empty" } ``` > [!note] Error format > The `error` field contains the error type (`"validation_failed"`) and the `details` field contains the specific validation message without any prefix. **Validation rules:** | Rule | Error Detail | |------|-------------| | No items array | `items array is required and must not be empty` | | More than 50 items | `maximum 50 items per request` | | Empty item text | `items[N].text is required` | | Text too long | `items[N].text exceeds 10000 characters` | | Title too long | `title exceeds 255 characters` | | Source too long | `items[N].source exceeds 255 characters` | | External ID too long | `items[N].external_id exceeds 255 characters` | | Energy override too long | `overrides.energy exceeds 20 characters` | | Priority override too long | `overrides.priority exceeds 20 characters` | | Label override too long | `overrides.label exceeds 100 characters` | | Project override too long | `overrides.project exceeds 100 characters` | | Bad date format in overrides | `overrides.date must be YYYY-MM-DD format` | ### Rate Limited `429` ```json { "error": "rate_limited" } ``` Includes `Retry-After: 60` header. See [[API-Reference/API-Reference#Rate Limiting|Rate Limiting]] for details. --- ## Webhook Delivery Logs Every webhook request is logged, whether it succeeds or fails. View delivery history using the [[API-Reference/Integrations#Get Webhook Logs|Get Webhook Logs]] endpoint. Logged information includes: - Number of items received and deduplicated - Success or failure status - Error message (if applicable) - Source identifier from the payload - Task ID (if auto-convert created a task) --- **Next:** Manage your Inbox items with [[API-Reference/Inbox|Inbox]]