Webhook

INFO

Webhooks are referenced by triggers via the notification.webhook perform action ({"notification.webhook": {"webhook_id": <id>}}). Create the webhook first, then point one or more triggers at its id.

List

Required permission: admin.webhook

GET-Request sent: /api/v1/webhooks

Details

// HTTP-Code 200 OK

[
  {
    "id": 1,
    "name": "Example webhook",
    "endpoint": "https://example.com/webhooks/incoming",
    "http_method": "post",
    "signature_token": "**********",
    "ssl_verify": true,
    "basic_auth_username": "user",
    "basic_auth_password": "**********",
    "bearer_token": null,
    "note": "Notifies an external system about ticket updates.",
    "pre_defined_webhook_type": null,
    "customized_payload": false,
    "custom_payload": null,
    "preferences": {},
    "active": true,
    "updated_by_id": 3,
    "created_by_id": 3,
    "created_at": "2026-09-24T12:31:34.578Z",
    "updated_at": "2026-09-24T12:31:44.512Z"
  }
]

INFO

signature_token, basic_auth_password and bearer_token are returned as ********** once they're set. The API never returns the stored secrets. Fields that aren't set are returned as null.

Show

Required permission: admin.webhook

GET-Request sent: /api/v1/webhooks/{id}

Details

// HTTP-Code 200 OK

{
  "id": 1,
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "**********",
  "ssl_verify": true,
  "basic_auth_username": "user",
  "basic_auth_password": "**********",
  "bearer_token": null,
  "note": "Notifies an external system about ticket updates.",
  "pre_defined_webhook_type": null,
  "customized_payload": false,
  "custom_payload": null,
  "preferences": {},
  "active": true,
  "updated_by_id": 3,
  "created_by_id": 3,
  "created_at": "2026-09-24T12:31:34.578Z",
  "updated_at": "2026-09-24T12:31:44.512Z"
}

Create

Required permission: admin.webhook

POST-Request sent: /api/v1/webhooks

Details

{
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "your-signature-token",
  "ssl_verify": true,
  "customized_payload": false,
  "note": "Notifies an external system about ticket updates.",
  "active": true
}

INFO

ssl_verify matters for https:// endpoints, set it true to actually validate the endpoint's TLS certificate. It only makes sense to set it false for a plain http:// endpoint, which has no certificate to verify in the first place.

Update

Required permission: admin.webhook

PUT-Request sent: /api/v1/webhooks/{id}

Payload shape is identical to Create. The response is the updated record, same shape as Show/Create with updated_at refreshed.

TIP

A partial payload works too, e.g. {"active": false} to toggle just that field.

Details

{
  "name": "Example webhook",
  "endpoint": "https://example.com/webhooks/incoming",
  "http_method": "post",
  "signature_token": "your-signature-token",
  "ssl_verify": true,
  "customized_payload": false,
  "note": "Notifies an external system about ticket updates.",
  "active": true,
  "id": 1
}

Delete

Required permission: admin.webhook

DANGER

This is a permanent removal

Please note that removing webhooks cannot be undone.

A webhook that is still referenced by the perform action of another object (e.g. a trigger) can't be deleted. The API responds with 422 Unprocessable Entity and lists the referencing objects. Remove the reference first.

DELETE-Request sent: /api/v1/webhooks/{id}

Details

// HTTP-Code 200 OK

{}

Details

// HTTP-Code 422 Unprocessable Entity

{
  "error": "This object is referenced by other object(s) and thus cannot be deleted: %s",
  "error_human": "This object is referenced by other object(s) and thus cannot be deleted: %s",
  "unprocessable_content": [
    "Trigger / Notify customer on auto-close (#5)"
  ]
}