Skip to content

Webhook delivery

Webhooks define where and how notifications are delivered to external systems.

A webhook connects a notification event to an external HTTP endpoint. When the event occurs, the system sends a request to the configured endpoint so that the receiving system can react to the change.

Webhooks only control delivery. They do not define when events occur or what data changes trigger them.

Webhook configuration

Each webhook connects three elements:

  • Event – the notification event that produces messages
  • Authentication – the method used to verify that the request originates from the system
  • Target URL – the external endpoint that receives the webhook request

This separation allows:

  • multiple webhooks to receive the same event
  • the same authentication configuration to be reused across integrations

A webhook always references exactly one event, but an event may be delivered to multiple webhooks.

Delivery request structure

When an event occurs, the system sends a webhook request with the following characteristics:

  • HTTP POST request
  • payload delivered as JSON
  • authentication headers included
  • request sent to the configured target URL

The request body contains the notification payload described in the Notification payload documentation.

A delivery attempt is considered successful only if the receiving system responds with:

HTTP 200

Any other response is treated as a failed delivery.

Security considerations

Webhook requests are authenticated using the configured authentication method.

Authentication allows the receiving system to verify:

  • that the request was sent by the system
  • that the payload has not been altered
  • that the request is recent and not a replay

Webhook endpoints should:

  • accept only HTTPS connections
  • validate the authentication headers
  • ignore duplicate events if they are received more than once

Notifications follow an at-least-once delivery model, meaning duplicate deliveries are possible and must be handled safely by the receiving system.

How-to

Related concepts