Ticket Webhooks

Ticket webhooks send HTTP POST requests to your URLs when ticket-related events occur. You can use them to sync tickets with external systems, trigger automations, or build custom notifications.

Supported events

Event	Description
`ticket.created`	A new ticket is created
`ticket.updated`	A ticket’s details are modified
`ticket.status_changed`	A ticket’s status changes
`ticket.resolved`	A ticket is marked as resolved
`ticket.closed`	A ticket is closed
`ticket.assigned`	A ticket is assigned to an agent
`ticket.sla_warning`	A ticket’s SLA is approaching its deadline
`ticket.sla_breached`	A ticket’s SLA deadline has passed
`message.created`	A new message is added to a ticket

Payload format

Every webhook delivery sends a JSON payload with this structure:

{
  "organizationId": "uuid",
  "eventType": "ticket.created",
  "eventId": "uuid",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    // Event-specific fields
  }
}

Field	Type	Description
`organizationId`	UUID	Your organization’s ID
`eventType`	string	One of the supported event types above
`eventId`	UUID	Unique identifier for this event
`timestamp`	ISO 8601	When the event occurred
`data`	object	Event-specific data (ticket details, message content, etc.)

Managing webhooks

Creating a webhook

To create a webhook, provide a name, HTTPS URL, and at least one event to subscribe to.

Field	Required	Description
`name`	Yes	A descriptive name (up to 200 characters)
`url`	Yes	HTTPS endpoint URL (up to 2,000 characters)
`events`	Yes	Array of event types to subscribe to (1–50 events)
`secret`	No	Signing secret for HMAC-SHA256 verification (16–500 characters)
`headers`	No	Custom HTTP headers to include in deliveries
`active`	No	Whether the webhook is active (default: true)
`retryPolicy`	No	Array of retry delays in seconds (up to 10 entries)

Limits

Maximum 20 webhooks per organization.
Webhook URLs must use HTTPS.
URLs cannot point to localhost, private IPs, or internal DNS suffixes.

Updating a webhook

All fields are optional when updating. Set secret to null to remove the signing secret.

Deleting a webhook

Deleting a webhook removes it and all associated delivery logs permanently.

Delivery and retries

Retry policy

When a delivery fails, it is retried according to the webhook’s retry policy. The default retry delays are:

Attempt	Delay
1st retry	1 second
2nd retry	5 seconds
3rd retry	30 seconds
4th retry	5 minutes
5th retry	30 minutes
6th retry	2 hours

You can customize the retry policy when creating or updating a webhook by providing an array of delays in seconds.

Auto-disable

After 10 consecutive failed deliveries, the webhook is automatically disabled and an admin notification is sent. Re-enable it manually after resolving the issue with your endpoint.

Delivery logs

Every delivery attempt is logged with:

Field	Description
`eventType`	The event that triggered the delivery
`payload`	The JSON payload that was sent
`responseStatus`	HTTP status code from your endpoint
`responseBody`	Response body (up to 4,096 bytes)
`attemptNumber`	Which attempt this was
`deliveredAt`	When the delivery succeeded (null if not yet delivered)
`failedAt`	When the delivery failed (null if not failed)
`nextRetryAt`	When the next retry is scheduled (null if no retry pending)

Retrying a delivery

You can manually retry a failed delivery from the delivery log. The delivery must not have already succeeded, and the webhook must be active.

Testing a webhook

Send a test payload to verify your endpoint is reachable and correctly processing requests. The test payload uses "test" as the event type:

{
  "organizationId": "your-org-id",
  "eventType": "test",
  "eventId": "generated-uuid",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "message": "This is a test delivery from the webhook system."
  }
}

Webhooks overview — how webhooks work and signature verification
Survey webhooks — webhooks for survey response events