This article explains how to create or clone, test, update, and use webhooks. For reference information, see the Webhooks resources in the Support API.

Note: Webhooks have an authentication parameter that enables integration with the destination system. For the purposes of this tutorial, we'll use token authentication. For more information, see Webhook security and authentication.

Creating a new webhook

When you create a new webhook, you must specify a name, the endpoint URL the webhook will connect to, the HTTP method, request format, and the type of authentication it will use. Before a webhook can be used, it must also be subscribed to a trigger or automation, which can be done at the time of creation or as an update later.

curl 'https://{subdomain}.zendesk.com/api/v2/webhooks' \    -d '{        "webhook":{            "name":"Name",            "endpoint":"{destination_endpoint_url}",            "http_method":"POST",            "request_format":"json",            "status":"active",            "subscriptions":[                "conditional_ticket_events"            ],            "authentication":{                "type":"bearer_token",                  "data":{                      "token":"{token}",                  },                "add_position":"header"            }        }    } \    -H 'Content-Type:application/json' \    -v -u '{email_address}:{password}' -X PUT    }'

To clone an existing webhook, you must use the clone_webhook_id parameter to specify the webhook that is being cloned. You don't need to include the create webhook request body when cloning a webhook.

Example

curl 'https://{subdomain}.zendesk.com/api/v2/webhooks?clone_webhook_id={webhook_id}' \    -H 'Content-Type:application/json' \    -v -u '{email_address}:{password}' -X POST

New webhooks are automatically assigned unique IDs. A new webhook created by cloning will have the same name as the original webhook with (copy) appended to the end. To change the name, use the webhook ID to update the webhook and specify the new name.

Connecting a webhook to a trigger or automation

After you create a webhook and subscribe it to a trigger or automation, you must also update the trigger or automation to notify the webhook. To do this, use the trigger or automation actions property's notification_webhook field. This field's value is an array of two strings specifiying the webhook's ID and the message body.

Example

{  "actions": [    {"field": "notification_webhook", "value": ["12345678", "Ticket {{ticket.id}} has been updated."]}  ]}

For more information about the actions property for trigger and automation objects, see Actions reference.

Monitoring webhooks

Note: The activity log for webhooks is in an open beta. If your account moves to a different pod for any reason, all webhook activity logs for the last seven dates are deleted.

An activity log captures all activity and the status of each invocation for each webhook in the last seven days:

GET /api/v2/webhooks/{webhook_id}/invocations/

You can filter the list in a variety of ways. For example, to see a record of all failed invocations in the last seven days, add the parameter filter[status] to your request:

GET /api/v2/webhooks/{webhook_id}}/invocations?filter[status]=failed

Webhook retry logic

If the first attempt isn't successful, webhook invocations are retried up to three times if the server receiving the request returns an HTTP error code response of 409. Additionally, HTTP error code responses of 429 and 503 are retried if they contain a retry-after header with a value that is less than 60 seconds from the time the response is received. Webhook requests that time out are retried up to five times. Consecutive failed requests won't deactivate the webhook.

Each invocation of a webhook has a unique id that can be used to get detailed information about the attempts made for that invocation:

GET /api/v2/webhooks/{webhook_id}/invocations/{invocation_id}/attempts