webhook_endpoint.verification

POST

The activation handshake of an endpoint, sent when it is created, when its URL changes and on POST /v1/webhook-endpoints/{id}/verify; every attempt has a new id and challenge. It is signed like every webhook; answer 2xx with {"challenge": "<data.challenge>"} (or the challenge as plain text).

Parameters

Header Parameters

webhook-id

required

string format: uuid

The id of this handshake attempt (UUIDv7), also the body id: new on every attempt and not an event (GET /v1/events does not know it). It only enters the signature.

webhook-timestamp

required

string

/^\d+$/

Unix time (seconds) of this attempt. Refuse values more than 5 minutes from your clock.

webhook-signature

required

string

Space-separated v1,<base64> signatures: HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<body> with the base64-decoded part of the whsec_ secret. Accept the request if any of them matches (there is one per valid secret during a rotation).

Request Body^required

Media typeapplication/json

The activation handshake of an endpoint, sent when it is created, when its URL changes and on POST /v1/webhook-endpoints/{id}/verify; every attempt has a new id and challenge. It is signed like every webhook; answer 2xx with {"challenge": "<data.challenge>"} (or the challenge as plain text).

object

id

required

This attempt’s id, also its webhook-id header: new on every attempt.

string format: uuid

type

required

string

Allowed value: webhook_endpoint.verification

environment

required

string

Allowed values: test live

createdAt

required

When this attempt was sent.

string format: date-time

data

required

object

webhookEndpointId

required

string format: uuid

challenge

required

Random value to echo back, new on every attempt: echo the one of this request.

string

Responses

2XX

The challenge, echoed.

Media typeapplication/json

object

challenge

required

string

Example ^generated

{
  "challenge": "example"
}