Webhooks

These endpoints need the webhooks scope. The Webhooks section covers the events, payloads, signatures and retries.

List webhooks

GET /v1/webhooks

Each webhook has id, workspaceId, name, url, events, headerNames (the names of its custom headers; values are never returned), active, lastTriggeredAt, failureCount and createdAt.

Create a webhook

POST /v1/webhooks

curl -X POST https://api.rankdebug.com/v1/webhooks \
  -H "X-API-Key: $RANKDEBUG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "8c1f4b2e-1a3d-4c55-9f0e-2b7d6a9c1e40",
    "name": "Site health alerts",
    "url": "https://hooks.yourbrand.com/rankdebug",
    "events": ["site_check.regression", "site_crawl.regression"]
  }'

The response is 201 and includes the signing secret. It is returned only here, so store it to verify deliveries. Custom header values are write-only and never returned. The signing headers, Content-Type, Content-Length and Host cannot be set as custom headers.

Update a webhook

PUT /v1/webhooks/{id}

Takes any of name, url, events, active, secret and headers. Setting active to true re-enables a paused webhook and resets its failure count. Sending a new secret rotates it, and the new value is returned once in this response. headers replaces the set: a null value keeps the stored value of an existing header, and headers: null clears them all.

Delete a webhook

DELETE /v1/webhooks/{id}

Send a test event

POST /v1/webhooks/{id}/test

Sends a webhook.test event to this endpoint only, whatever it subscribes to.

Deliveries

GET /v1/webhooks/{id}/deliveries

Every delivery attempt to this webhook, newest first, kept for 30 days. Filter with status (success or failed) and limit (1 to 200, default 50). Each attempt has the event, the deliveryKey shared by every attempt of one event, the attempt number, status, the responseStatus and up to 500 characters of the response with secrets redacted, durationMs, a hash of the body sent, and nextRetryAt when another attempt is scheduled.

GET /v1/webhooks/{id}/deliveries/{deliveryId}

One attempt, including the payload exactly as it was sent.

Redeliver

POST /v1/webhooks/{id}/deliveries/{deliveryId}/redeliver

Sends the delivery again with the identical body, so the body signature and the delivery id match the original. Only the timestamp and the timestamped signature are new. It is one attempt, logged as the next attempt of that delivery. A paused webhook answers 409.