Webhooks

List webhook endpoints

Endpoints of this environment, newest first. Secrets are never included.

Secret key scope (any of): webhooks:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/webhooks" \
  -H "Authorization: Bearer $SECRET_KEY"

Create a webhook endpoint

Registers an https endpoint for a set of event types and returns its signing secret.

Secret reveal. The response secret (whsec_…) is returned exactly once, here and when you rotate it: store it now. It is the HMAC-SHA256 key of the X-BeckLink-Signature header (t=<unix>,v1=<hex>, signed over <t>.<raw body>).

The URL must be https with a public host name (no IP addresses, local names or private networks). An environment holds at most 20 endpoints (409 conflict). click.created is high volume: subscribe to it deliberately.

Secret key scope (any of): webhooks:write

Request body

Responses

Example

curl -X POST "https://api.becklinks.com/v1/webhooks" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"string","events":["click.created"]}'

Get a webhook endpoint

One endpoint with its subscription, status and failure streak (no secret).

Secret key scope (any of): webhooks:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/webhooks/{webhook}" \
  -H "Authorization: Bearer $SECRET_KEY"

Update a webhook endpoint

Changes the URL, description, event types or status. status: "active" also turns an endpoint on that was disabled, automatically included, and clears its failure streak. A changed URL is checked like on creation.

Secret key scope (any of): webhooks:write

Parameters

Request body

Responses

Example

curl -X PATCH "https://api.becklinks.com/v1/webhooks/{webhook}" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a webhook endpoint

Deletes the endpoint and its delivery log for good. Events already queued for it are dropped. Disable the endpoint instead to keep the log.

Secret key scope (any of): webhooks:write

Parameters

Responses

Example

curl -X DELETE "https://api.becklinks.com/v1/webhooks/{webhook}" \
  -H "Authorization: Bearer $SECRET_KEY"

List deliveries

The delivery log of an endpoint, newest first, with the first 2 KB of request and response. Kept 30 days. from and to bound the time window (default: the last 7 days; at most 30 days wide); filter by status and event_type.

Secret key scope (any of): webhooks:write

Parameters

Responses

Example

curl -X GET "https://api.becklinks.com/v1/webhooks/{webhook}/deliveries" \
  -H "Authorization: Bearer $SECRET_KEY"

Replay a delivery

Sends the event of a finished delivery again as one more attempt (same event id, so receivers can deduplicate). A replay is a single attempt without automatic retries. The attempt is queued for the delivery worker; the returned delivery is pending and finishes within seconds (list the deliveries to see the result). Answers 503 service_unavailable, writing nothing, when the server has no job queue connection.

Secret key scope (any of): webhooks:write

Parameters

Responses

Example

curl -X POST "https://api.becklinks.com/v1/webhooks/{webhook}/deliveries/{delivery}/replay" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Rotate the signing secret

Generates a new signing secret and returns it once. The previous secret keeps working for 24 hours: during that time every delivery carries two v1 signatures (new first), so you can switch your receiver at any moment. Rotating again replaces the previous secret.

Secret key scope (any of): webhooks:write

Parameters

Responses

Example

curl -X POST "https://api.becklinks.com/v1/webhooks/{webhook}/rotate-secret" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Send a test event

Sends a sample event (a fresh event id, labelled test data) of the endpoint’s first subscribed type. Single attempt, no retries. The attempt is queued for the delivery worker; the returned delivery is pending and finishes within seconds (list the deliveries to see the result). Answers 503 service_unavailable, writing nothing, when the server has no job queue connection.

Secret key scope (any of): webhooks:write

Parameters

Responses

Example

curl -X POST "https://api.becklinks.com/v1/webhooks/{webhook}/test" \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"