Skip to main content

Webhook

Webhooks send changes to your records to your own HTTPS endpoint.

📄️ Add webhook

Adds a webhook for the current company (the impersonated user's company when impersonating) that sends changes to its `entity` records to `url`. `add`, `update` and `remove` choose which changes are sent. `statusIds` is only allowed for `Account` webhooks. An `Account` webhook with no `workflowId` gets every account, in any workflow or none, narrowed only by the `statusIds`, `workflowStageIds` and `workflowActionIds` it sets. With a `workflowId`, it gets accounts in that workflow (narrowed by `workflowStageIds` and `workflowActionIds`) and accounts in no workflow (narrowed by `statusIds`). Requires the `webhook:manage` permission in the webhook's company (the current company for add and list). Webhooks with `entity` `Company` can only be added or changed by Terros staff. `url` must use HTTPS, and must not point at an internal host name (such as `localhost` or a `.local` or `.internal` name) or at a private, loopback or link-local IPv4 or IPv6 address, checked when the webhook is added or changed. `headers` are stored with the webhook but never returned by any webhook endpoint, because they can hold the receiver's credentials. Webhook deliveries do not currently send them. A new webhook can take up to 5 minutes to start receiving deliveries.

📄️ List webhooks

Lists the current company's webhooks (the impersonated user's company when impersonating). Requires the `webhook:manage` permission in the webhook's company (the current company for add and list). Webhooks with `entity` `Company` can only be added or changed by Terros staff. `Company` webhooks are listed for any caller with that permission. Every listed `url` passed the URL rule when it was saved: `url` must use HTTPS, and must not point at an internal host name (such as `localhost` or a `.local` or `.internal` name) or at a private, loopback or link-local IPv4 or IPv6 address, checked when the webhook is added or changed. `headers` are stored with the webhook but never returned by any webhook endpoint, because they can hold the receiver's credentials. Webhook deliveries do not currently send them. The list shows saved changes at once, but deliveries can lag them by up to 5 minutes. Use `/webhook/history` to see whether deliveries worked.

📄️ Update webhook

Changes a webhook. Send the webhook from `/webhook/list` with your changes: `name` and `description` are cleared when omitted, other omitted fields keep their current values, `target: null` clears the target, and `entity` cannot be changed. Omit `headers` to keep the stored ones. An `Account` webhook with no `workflowId` gets every account, in any workflow or none, narrowed only by the `statusIds`, `workflowStageIds` and `workflowActionIds` it sets. With a `workflowId`, it gets accounts in that workflow (narrowed by `workflowStageIds` and `workflowActionIds`) and accounts in no workflow (narrowed by `statusIds`). Requires the `webhook:manage` permission in the webhook's company (the current company for add and list). Webhooks with `entity` `Company` can only be added or changed by Terros staff. `url` must use HTTPS, and must not point at an internal host name (such as `localhost` or a `.local` or `.internal` name) or at a private, loopback or link-local IPv4 or IPv6 address, checked when the webhook is added or changed. Changes can take up to 5 minutes to affect deliveries.

📄️ List webhook deliveries

Lists a webhook's deliveries, newest first, up to 1,000: each row's `webhookDate` (when it was sent), `status` and, for a failure, `webhookError`. Deliveries are kept for 30 days. Filter by delivery time with `startTime` and `endTime`. Payloads contain customer data and are left out unless `includePayload` is `true`. Requires the `webhook:manage` permission in the webhook's company (the current company for add and list). Reading a `Company` webhook's history does not require Terros staff. Deliveries only go to `url`s that passed the HTTPS and blocked-host URL rule on `/webhook/add` and `/webhook/update`. A webhook added or changed in the last 5 minutes may not have deliveries yet, because changes can take up to 5 minutes to affect deliveries.

📄️ Get sample webhook payloads

Returns sample payloads for `entity` (or every entity when omitted), to build a receiver before adding a webhook with `/webhook/add`. The samples are made up, not your data. Any signed-in user can call it, without the `webhook:manage` permission that adding the webhook needs; `Company` samples require Terros staff, like `Company` webhooks. Real deliveries go only to a `url` that passed the HTTPS and blocked-host URL rule, and can take up to 5 minutes to start after the webhook is added or changed.