Webhooks
Create
Creates a webhook subscription: an https URL, the event types to deliver ("ticket.created", "ticket.updated", "ticket.replied", "ticket.assignee_changed") and optionally a custom header sent with every delivery as a security gate on your side. The response contains the signing secret exactly once - store it to verify the X-Deskhero-Signature header (hex HMAC-SHA256 of "timestamp.body"). URLs whose hosts resolve to private addresses are rejected, and at most 10 webhooks can exist per workspace.
POST
/api/{tenant:minlength(2)}/v{version:apiVersion}/webhooks
Request arguments
| Name | Type | Source |
|---|---|---|
| input | DTO_webhook_subscription_input | Body |
Request body example
Response
Response body example
DTO_webhook_subscription_input
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| label | String | Label | |
| url | String | Https endpoint to POST deliveries to. Hosts resolving to private addresses are rejected | |
| event_types | String[] | Public event names to listen to, e.g. ["ticket.created", "ticket.updated"] | |
| custom_header_name | String | Optional header sent with every delivery (e.g. "Authorization"), usable as a security gate on the receiving side | |
| custom_header_value | String | Value for the custom header. Stored encrypted, never returned. On update: omit (null) to keep the current value, empty string to clear it | |
| enabled | Boolean (nullable) | Only honored on update (subscriptions are created enabled). Re-enabling resets the failure counter |
DTO_webhook_subscription
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| id | Int32 | Id | |
| label | String | Label | |
| url | String | Url | |
| event_types | String[] | Public event names this subscription listens to, e.g. "ticket.created" | |
| secret | String | ReadOnly | Only returned on create and rotate_secret - store it, it cannot be retrieved again |
| custom_header_name | String | Custom header name | |
| custom_header_value_set | Boolean | ReadOnly | Whether a custom header value is configured. The value itself is never returned |
| enabled | Boolean | Enabled | |
| disabled_reason | String | ReadOnly | Why the subscription is disabled: "user" or "auto_failures" (empty when enabled) |
| consecutive_failure_count | Int32 | ReadOnly | Consecutive failure count |
| last_success | DateTime (nullable) | ReadOnly | Last success |
| last_failure | DateTime (nullable) | ReadOnly | Last failure |
| created | DateTime | ReadOnly | Created |
| last_updated | DateTime | ReadOnly | Last updated |
Generated Aug 31, 2026 16:21