Anatomy of a webhook request

The following is a sample webhook request:

{  "request": {    "endpoint": "https://example.com/status/200",    "http_method": "POST",    "payload": "{\"name\":\"test webhook\"}",    "request_format": "json"  }}

Webhooks send an HTTP request to a specified URL in response to an event, such as a trigger or automation firing in Zendesk Support. They are typically used to invoke behavior in another system.

After you create a webhook and connect it to a trigger or automation, whenever the trigger or automation fires it notifies the webhook and, in turn, the webhook sends an HTTP request to the destination system. The webhook request contains a JSON payload and an HTTP header that provides context.

Request header

Webhooks use HTTP headers to provide important information, but some headers are particularly useful. For example, the x-zendesk-webhook-signature and x-zendesk-webhook-signature-timestamp are used together to verify that the request came from a particular webhook. The following example shows the HTTP headers that are included in a webhook's request:

x-zendesk-webhook-id: 01F1KRFQ6BG29CNWFR60NK5FNYx-zendesk-webhook-invocation-id: 8350205582x-zendesk-webhook-signature: EiqWE3SXTPQpPulBV6OSuuGziIishZNc1VwNZYqZrHU=x-zendesk-webhook-signature-timestamp: 2021-03-25T05:09:27Z

For more information about authenticating webhook requests, see Verifying webhook authenticity.

JSON payload

The JSON payload is the information the webhook is communicating with the request. It includes the endpoint on the destination system it is sending the request to. In this example, that's "endpoint": "https://example.com/status/200". The JSON payload also specifies the HTTP method for the request (in this case, http_method": "POST") and the format of the request ("request_format": "json"). Finally, the payload of the webhook request contains the specific message you're trying to send to the destination system. In the example webhook above, the payload is "payload": "{\"name\":\"test webhook\"}".

For reference information, see the Webhooks resources in the Support API.