Webhook
Webhook subscriptions. Register an HTTPS endpoint, choose which events it receives, and Nifty POSTs each matching event to it signed with an HMAC-SHA256 secret. That secret is returned exactly once — at creation, and again from rotateSecret — and is never readable afterwards.
List Webhooks
List webhooks. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by -createdAt unless you pass sort.
Required scope: webhooks:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: -createdAt.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
purgeAt[null]Filter where purgeAt is null (pass true).
purgeAt[notNull]Filter where purgeAt is not null (pass true).
purgeAt[gt]Filter where purgeAt is greater than.
purgeAt[gte]Filter where purgeAt is greater than or equal to.
purgeAt[lt]Filter where purgeAt is less than.
purgeAt[lte]Filter where purgeAt is less than or equal to.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
active[eq]Filter where active equals.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
List Webhooks › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create Webhook
Create a Webhook. Server-assigned fields are ignored if sent.
Required scope: webhooks:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create Webhook › Request Body
nameHuman-readable label for this endpoint, shown in the integrations UI.
url^https:\/\/ · requiredThe HTTPS endpoint each matching event is POSTed to.
Verifying a delivery. Every request carries an X-Webhook-Signature header of the form t=<unix_seconds>,v1=<hex>, where the hex is an HMAC-SHA256 of ${t}.${rawBody} keyed with this webhook's secret. Reject a request whose t is more than 300 seconds away from your own clock — that window is what stops a captured request being replayed at you.
Delivery semantics. Each event is attempted up to 4 times (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (active flips to false) and you will have to re-enable it; any success resets that counter and updates lastDeliveredAt. Send POST /webhooks/{id}/test to fire a synthetic delivery at your endpoint before going live.
eventsWhich events this webhook receives.
Grammar. An entry is either an exact event name such as task.created, or a pattern. In a pattern each * stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so task.* matches task.created and task.updated but NOT the three-segment task.assignees.added; reach those with task.*.*, or by exact name. The bare * is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the event catalog is rejected at registration, so subscribe using the values listed below.
Lifecycle events. Each resource below emits all five of created, updated, removed, restored and force_deleted, as {resource}.{action}:
annotation, chat, checkIn, checkInRequest, checklist, checklistItem, document, favorite, favoriteFolder, file, form, goal, goalGroup, label, list, member, message, portfolio, project, projectDashboard, projectFolder, recurringRule, reminder, reportChart, role, status, task, taskHandoff, presenceStatus, timeEntry, webhook.
Membership events. {resource}.{relation}.added and {resource}.{relation}.removed fire when a link is made or broken — one pair per relation listed here:
checkIn—assignees,subscriberscheckInRequest—assigneesfile—labels,subscriberslist—assignees,goals,hiddenForportfolio—membersreportChart—projectsstatus—assignees,hiddenFortask—assignees,connectedTasks,hiddenFor,labels,subscribers
Operation events. Each named operation emits an event of the same name — the verb, not a past tense: document.append, document.editText, file.createFromContent, file.createUploadUrl, file.uploadFromUrl, project.addMember, project.removeMember, project.transfer, task.attachDocument, task.createTree, task.detachDocument, webhook.rotateSecret, webhook.test.
apiVersionWhich payload format your endpoint receives, echoed back to you as the X-Api-Version request header. latest follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to latest.
activeWhether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.
Create Webhook › Responses
Created
idUnique identifier. Server-minted, stable, opaque.
createdAtCreation timestamp.
nameHuman-readable label for this endpoint, shown in the integrations UI.
urlThe HTTPS endpoint each matching event is POSTed to.
Verifying a delivery. Every request carries an X-Webhook-Signature header of the form t=<unix_seconds>,v1=<hex>, where the hex is an HMAC-SHA256 of ${t}.${rawBody} keyed with this webhook's secret. Reject a request whose t is more than 300 seconds away from your own clock — that window is what stops a captured request being replayed at you.
Delivery semantics. Each event is attempted up to 4 times (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (active flips to false) and you will have to re-enable it; any success resets that counter and updates lastDeliveredAt. Send POST /webhooks/{id}/test to fire a synthetic delivery at your endpoint before going live.
eventsWhich events this webhook receives.
Grammar. An entry is either an exact event name such as task.created, or a pattern. In a pattern each * stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so task.* matches task.created and task.updated but NOT the three-segment task.assignees.added; reach those with task.*.*, or by exact name. The bare * is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the event catalog is rejected at registration, so subscribe using the values listed below.
Lifecycle events. Each resource below emits all five of created, updated, removed, restored and force_deleted, as {resource}.{action}:
annotation, chat, checkIn, checkInRequest, checklist, checklistItem, document, favorite, favoriteFolder, file, form, goal, goalGroup, label, list, member, message, portfolio, project, projectDashboard, projectFolder, recurringRule, reminder, reportChart, role, status, task, taskHandoff, presenceStatus, timeEntry, webhook.
Membership events. {resource}.{relation}.added and {resource}.{relation}.removed fire when a link is made or broken — one pair per relation listed here:
checkIn—assignees,subscriberscheckInRequest—assigneesfile—labels,subscriberslist—assignees,goals,hiddenForportfolio—membersreportChart—projectsstatus—assignees,hiddenFortask—assignees,connectedTasks,hiddenFor,labels,subscribers
Operation events. Each named operation emits an event of the same name — the verb, not a past tense: document.append, document.editText, file.createFromContent, file.createUploadUrl, file.uploadFromUrl, project.addMember, project.removeMember, project.transfer, task.attachDocument, task.createTree, task.detachDocument, webhook.rotateSecret, webhook.test.
apiVersionWhich payload format your endpoint receives, echoed back to you as the X-Api-Version request header. latest follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to latest.
activeWhether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.
failCountConsecutive delivery failures. Reset to 0 on any success; at 10 the webhook is automatically deactivated.
secretThe signing secret for this webhook, in plaintext. Returned exactly once — here, and again from POST /webhooks/{id}/rotate-secret — and never readable afterwards, so store it before you do anything else. Use it to verify the X-Webhook-Signature header on every delivery. If you lose it, rotate: POST /webhooks/{id}/rotate-secret mints a new one and invalidates the old. NOTE: replaying this exact request with the same Idempotency-Key returns the body WITHOUT secret — once means once.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who deleted this webhook. A member id — resolve it with GET /members/{id}.
createdByIdTeam member who registered this webhook. Server-set from the caller identity; a member id, so resolve it with GET /members/{id}.
lastDeliveredAtWhen a delivery to this endpoint last succeeded. null if it has never delivered.
Get Webhook
Retrieve a single Webhook by id.
Required scope: webhooks:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Webhook.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Webhook › Responses
OK
idUnique identifier. Server-minted, stable, opaque.
createdAtCreation timestamp.
nameHuman-readable label for this endpoint, shown in the integrations UI.
urlThe HTTPS endpoint each matching event is POSTed to.
Verifying a delivery. Every request carries an X-Webhook-Signature header of the form t=<unix_seconds>,v1=<hex>, where the hex is an HMAC-SHA256 of ${t}.${rawBody} keyed with this webhook's secret. Reject a request whose t is more than 300 seconds away from your own clock — that window is what stops a captured request being replayed at you.
Delivery semantics. Each event is attempted up to 4 times (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (active flips to false) and you will have to re-enable it; any success resets that counter and updates lastDeliveredAt. Send POST /webhooks/{id}/test to fire a synthetic delivery at your endpoint before going live.
eventsWhich events this webhook receives.
Grammar. An entry is either an exact event name such as task.created, or a pattern. In a pattern each * stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so task.* matches task.created and task.updated but NOT the three-segment task.assignees.added; reach those with task.*.*, or by exact name. The bare * is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the event catalog is rejected at registration, so subscribe using the values listed below.
Lifecycle events. Each resource below emits all five of created, updated, removed, restored and force_deleted, as {resource}.{action}:
annotation, chat, checkIn, checkInRequest, checklist, checklistItem, document, favorite, favoriteFolder, file, form, goal, goalGroup, label, list, member, message, portfolio, project, projectDashboard, projectFolder, recurringRule, reminder, reportChart, role, status, task, taskHandoff, presenceStatus, timeEntry, webhook.
Membership events. {resource}.{relation}.added and {resource}.{relation}.removed fire when a link is made or broken — one pair per relation listed here:
checkIn—assignees,subscriberscheckInRequest—assigneesfile—labels,subscriberslist—assignees,goals,hiddenForportfolio—membersreportChart—projectsstatus—assignees,hiddenFortask—assignees,connectedTasks,hiddenFor,labels,subscribers
Operation events. Each named operation emits an event of the same name — the verb, not a past tense: document.append, document.editText, file.createFromContent, file.createUploadUrl, file.uploadFromUrl, project.addMember, project.removeMember, project.transfer, task.attachDocument, task.createTree, task.detachDocument, webhook.rotateSecret, webhook.test.
apiVersionWhich payload format your endpoint receives, echoed back to you as the X-Api-Version request header. latest follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to latest.
activeWhether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.
failCountConsecutive delivery failures. Reset to 0 on any success; at 10 the webhook is automatically deactivated.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who deleted this webhook. A member id — resolve it with GET /members/{id}.
createdByIdTeam member who registered this webhook. Server-set from the caller identity; a member id, so resolve it with GET /members/{id}.
lastDeliveredAtWhen a delivery to this endpoint last succeeded. null if it has never delivered.
Delete Webhook
Move this Webhook to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.
Required scope: webhooks:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Webhook.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete Webhook › Responses
No Content
Update Webhook
Partially update a Webhook. Only the fields you send are changed.
Required scope: webhooks:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Webhook.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update Webhook › Request Body
nameHuman-readable label for this endpoint, shown in the integrations UI.
url^https:\/\/The HTTPS endpoint each matching event is POSTed to.
Verifying a delivery. Every request carries an X-Webhook-Signature header of the form t=<unix_seconds>,v1=<hex>, where the hex is an HMAC-SHA256 of ${t}.${rawBody} keyed with this webhook's secret. Reject a request whose t is more than 300 seconds away from your own clock — that window is what stops a captured request being replayed at you.
Delivery semantics. Each event is attempted up to 4 times (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (active flips to false) and you will have to re-enable it; any success resets that counter and updates lastDeliveredAt. Send POST /webhooks/{id}/test to fire a synthetic delivery at your endpoint before going live.
eventsWhich events this webhook receives.
Grammar. An entry is either an exact event name such as task.created, or a pattern. In a pattern each * stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so task.* matches task.created and task.updated but NOT the three-segment task.assignees.added; reach those with task.*.*, or by exact name. The bare * is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the event catalog is rejected at registration, so subscribe using the values listed below.
Lifecycle events. Each resource below emits all five of created, updated, removed, restored and force_deleted, as {resource}.{action}:
annotation, chat, checkIn, checkInRequest, checklist, checklistItem, document, favorite, favoriteFolder, file, form, goal, goalGroup, label, list, member, message, portfolio, project, projectDashboard, projectFolder, recurringRule, reminder, reportChart, role, status, task, taskHandoff, presenceStatus, timeEntry, webhook.
Membership events. {resource}.{relation}.added and {resource}.{relation}.removed fire when a link is made or broken — one pair per relation listed here:
checkIn—assignees,subscriberscheckInRequest—assigneesfile—labels,subscriberslist—assignees,goals,hiddenForportfolio—membersreportChart—projectsstatus—assignees,hiddenFortask—assignees,connectedTasks,hiddenFor,labels,subscribers
Operation events. Each named operation emits an event of the same name — the verb, not a past tense: document.append, document.editText, file.createFromContent, file.createUploadUrl, file.uploadFromUrl, project.addMember, project.removeMember, project.transfer, task.attachDocument, task.createTree, task.detachDocument, webhook.rotateSecret, webhook.test.
apiVersionWhich payload format your endpoint receives, echoed back to you as the X-Api-Version request header. latest follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to latest.
activeWhether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update Webhook › Responses
OK
idUnique identifier. Server-minted, stable, opaque.
createdAtCreation timestamp.
nameHuman-readable label for this endpoint, shown in the integrations UI.
urlThe HTTPS endpoint each matching event is POSTed to.
Verifying a delivery. Every request carries an X-Webhook-Signature header of the form t=<unix_seconds>,v1=<hex>, where the hex is an HMAC-SHA256 of ${t}.${rawBody} keyed with this webhook's secret. Reject a request whose t is more than 300 seconds away from your own clock — that window is what stops a captured request being replayed at you.
Delivery semantics. Each event is attempted up to 4 times (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (active flips to false) and you will have to re-enable it; any success resets that counter and updates lastDeliveredAt. Send POST /webhooks/{id}/test to fire a synthetic delivery at your endpoint before going live.
eventsWhich events this webhook receives.
Grammar. An entry is either an exact event name such as task.created, or a pattern. In a pattern each * stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so task.* matches task.created and task.updated but NOT the three-segment task.assignees.added; reach those with task.*.*, or by exact name. The bare * is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the event catalog is rejected at registration, so subscribe using the values listed below.
Lifecycle events. Each resource below emits all five of created, updated, removed, restored and force_deleted, as {resource}.{action}:
annotation, chat, checkIn, checkInRequest, checklist, checklistItem, document, favorite, favoriteFolder, file, form, goal, goalGroup, label, list, member, message, portfolio, project, projectDashboard, projectFolder, recurringRule, reminder, reportChart, role, status, task, taskHandoff, presenceStatus, timeEntry, webhook.
Membership events. {resource}.{relation}.added and {resource}.{relation}.removed fire when a link is made or broken — one pair per relation listed here:
checkIn—assignees,subscriberscheckInRequest—assigneesfile—labels,subscriberslist—assignees,goals,hiddenForportfolio—membersreportChart—projectsstatus—assignees,hiddenFortask—assignees,connectedTasks,hiddenFor,labels,subscribers
Operation events. Each named operation emits an event of the same name — the verb, not a past tense: document.append, document.editText, file.createFromContent, file.createUploadUrl, file.uploadFromUrl, project.addMember, project.removeMember, project.transfer, task.attachDocument, task.createTree, task.detachDocument, webhook.rotateSecret, webhook.test.
apiVersionWhich payload format your endpoint receives, echoed back to you as the X-Api-Version request header. latest follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to latest.
activeWhether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.
failCountConsecutive delivery failures. Reset to 0 on any success; at 10 the webhook is automatically deactivated.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who deleted this webhook. A member id — resolve it with GET /members/{id}.
createdByIdTeam member who registered this webhook. Server-set from the caller identity; a member id, so resolve it with GET /members/{id}.
lastDeliveredAtWhen a delivery to this endpoint last succeeded. null if it has never delivered.
Test (Webhook)
Send a synthetic test event to this webhook's registered URL and report whether the endpoint accepted it. Use it to verify connectivity and signature verification before relying on live events.
Required scope: webhooks:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Webhook.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Test (Webhook) › Responses
OK
idempotentReplayTrue when this response was replayed from a previous call with the same Idempotency-Key (no new delivery was attempted).
deliveredTrue when the endpoint answered with a 2xx status.
statusCodeHTTP status returned by the endpoint. Absent when no response was received (DNS failure, refused connection, timeout).
errorShort reason the test delivery failed. Absent when delivered is true.
Rotate secret (Webhook)
Mint a new HMAC signing secret for this webhook and return it. The new secret is shown exactly once in this response — the previous secret stops verifying immediately.
Required scope: webhooks:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Webhook.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Rotate secret (Webhook) › Responses
OK
idcreatedAtnameurleventsapiVersionactivefailCountsecretThe signing secret for this webhook, in plaintext. Returned exactly once — here, and again from POST /webhooks/{id}/rotate-secret — and never readable afterwards, so store it before you do anything else. Use it to verify the X-Webhook-Signature header on every delivery. If you lose it, rotate: POST /webhooks/{id}/rotate-secret mints a new one and invalidates the old. NOTE: replaying this exact request with the same Idempotency-Key returns the body WITHOUT secret — once means once.
updatedAtcreatedByActorIdupdatedByActorIdcreatedByActorTypeupdatedByActorTypepurgeAtdeletedByIdcreatedByIdlastDeliveredAtDeliveries (Webhook)
List recent delivery attempts for this webhook, newest first — what was sent, whether the endpoint accepted it, and why it failed if it did not. Attempts are kept for 30 days.
Required scope: webhooks:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Webhook.
query Parameters
limitHow many delivery attempts to return, newest first. Between 1 and 100; defaults to 25.
Deliveries (Webhook) › Responses
OK
The page of delivery attempts, newest first.
limitThe page size that was applied.
hasMoreTrue when older attempts exist beyond this page. Ask for a larger page to see more.
Restore Webhook
Restore a Webhook that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.
Required scope: webhooks:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Webhook.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Restore Webhook › Responses
OK
idUnique identifier. Server-minted, stable, opaque.
createdAtCreation timestamp.
nameHuman-readable label for this endpoint, shown in the integrations UI.
urlThe HTTPS endpoint each matching event is POSTed to.
Verifying a delivery. Every request carries an X-Webhook-Signature header of the form t=<unix_seconds>,v1=<hex>, where the hex is an HMAC-SHA256 of ${t}.${rawBody} keyed with this webhook's secret. Reject a request whose t is more than 300 seconds away from your own clock — that window is what stops a captured request being replayed at you.
Delivery semantics. Each event is attempted up to 4 times (the first try plus 3 retries) before it is given up on. Ten consecutive failed deliveries deactivate the webhook (active flips to false) and you will have to re-enable it; any success resets that counter and updates lastDeliveredAt. Send POST /webhooks/{id}/test to fire a synthetic delivery at your endpoint before going live.
eventsWhich events this webhook receives.
Grammar. An entry is either an exact event name such as task.created, or a pattern. In a pattern each * stands for exactly ONE dot-segment, and an entry may carry at most 4 of them — so task.* matches task.created and task.updated but NOT the three-segment task.assignees.added; reach those with task.*.*, or by exact name. The bare * is the one exception: it is a catch-all that matches every event, at any segment count. An entry matching nothing in the event catalog is rejected at registration, so subscribe using the values listed below.
Lifecycle events. Each resource below emits all five of created, updated, removed, restored and force_deleted, as {resource}.{action}:
annotation, chat, checkIn, checkInRequest, checklist, checklistItem, document, favorite, favoriteFolder, file, form, goal, goalGroup, label, list, member, message, portfolio, project, projectDashboard, projectFolder, recurringRule, reminder, reportChart, role, status, task, taskHandoff, presenceStatus, timeEntry, webhook.
Membership events. {resource}.{relation}.added and {resource}.{relation}.removed fire when a link is made or broken — one pair per relation listed here:
checkIn—assignees,subscriberscheckInRequest—assigneesfile—labels,subscriberslist—assignees,goals,hiddenForportfolio—membersreportChart—projectsstatus—assignees,hiddenFortask—assignees,connectedTasks,hiddenFor,labels,subscribers
Operation events. Each named operation emits an event of the same name — the verb, not a past tense: document.append, document.editText, file.createFromContent, file.createUploadUrl, file.uploadFromUrl, project.addMember, project.removeMember, project.transfer, task.attachDocument, task.createTree, task.detachDocument, webhook.rotateSecret, webhook.test.
apiVersionWhich payload format your endpoint receives, echoed back to you as the X-Api-Version request header. latest follows the newest format and can change without notice; pin a dated version if you need stability. Defaults to latest.
activeWhether deliveries are attempted. Set it false to pause the webhook without deleting it. The server also flips it false by itself after 10 consecutive failed deliveries; any success resets that counter.
failCountConsecutive delivery failures. Reset to 0 on any success; at 10 the webhook is automatically deactivated.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdTeam member who deleted this webhook. A member id — resolve it with GET /members/{id}.
createdByIdTeam member who registered this webhook. Server-set from the caller identity; a member id, so resolve it with GET /members/{id}.
lastDeliveredAtWhen a delivery to this endpoint last succeeded. null if it has never delivered.