Webhooks

The webhooks endpoints manage persistent endpoints that receive signed job.succeeded and job.failed events. For the event flow, payloads, and signature verification, see the Webhooks guide; this page is the CRUD reference.

Method	Path	What it does
POST	/v1/webhooks	Register an endpoint; returns the secret once
GET	/v1/webhooks	List your webhooks (without secrets)
DELETE	/v1/webhooks/{id}	Remove a webhook; delivery stops immediately
GET	/v1/webhooks/{id}/deliveries	List delivery attempts for one webhook

curl "https://api.rolesapi.com/v1/webhooks" \
  -H "Authorization: Bearer rk_live_your_key"

POST /v1/webhooks

Parameter	In	Type	Required	Description
url	body	string	Yes	HTTPS endpoint to deliver events to.
events	body	string[]	No	Any of job.succeeded, job.failed. Default: both.

curl -X POST "https://api.rolesapi.com/v1/webhooks" \
  -H "Authorization: Bearer rk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/rolesapi", "events": ["job.succeeded", "job.failed"]}'

{
  "data": {
    "id": "wh_01habc",
    "url": "https://example.com/hooks/rolesapi",
    "events": ["job.succeeded", "job.failed"],
    "secret": "whsec_9f2c4e6a8b0d1f3a5c7e9b2d4f6a8c0e",
    "active": true,
    "created_at": "2026-07-01T09:15:00Z"
  },
  "request_id": "req_0b3d55e7"
}

The secret appears only in this response. It is used to sign every delivery (x-rolesapi-signature); store it in a secrets manager immediately. It cannot be retrieved later — to get a new secret, delete the webhook and create another.

Errors: 400 invalid_request for a non-HTTPS URL or unknown event name.

GET /v1/webhooks

Returns your webhooks in the standard list envelope. The webhook object:

Field	Type	Meaning
id	string	Webhook id, wh_....
url	string	Destination endpoint.
events	string[]	Subscribed events.
active	boolean	Whether deliveries are being attempted.
created_at	string	ISO 8601.
last_delivery_at	string or null	Time of the most recent delivery attempt.

The secret field is never included after creation.

DELETE /v1/webhooks/{id}

curl -X DELETE "https://api.rolesapi.com/v1/webhooks/wh_01habc" \
  -H "Authorization: Bearer rk_live_your_key"

Deletion is immediate — no further deliveries are attempted, including retries of past failures. 404 not_found if the id does not exist on your account.

GET /v1/webhooks/{id}/deliveries

Lists delivery attempts, newest first, with limit/offset pagination. Use it to debug an endpoint that is not receiving events.

{
  "data": [
    {
      "id": "whd_01hdef",
      "webhook_id": "wh_01habc",
      "event": "job.succeeded",
      "status": "succeeded",
      "attempt": 2,
      "response_status": 200,
      "created_at": "2026-07-01T09:33:05Z"
    },
    {
      "id": "whd_01hdee",
      "webhook_id": "wh_01habc",
      "event": "job.succeeded",
      "status": "failed",
      "attempt": 1,
      "response_status": 503,
      "created_at": "2026-07-01T09:32:41Z"
    }
  ],
  "meta": { "total": 2, "count": 2, "limit": 50, "offset": 0, "has_more": false },
  "request_id": "req_7f19c30a"
}

Field	Type	Meaning
id	string	Delivery id, whd_....
event	string	job.succeeded or job.failed.
status	string	succeeded (2xx received) or failed.
attempt	integer	1 for the first try, incrementing on each retry.
response_status	integer or null	HTTP status your endpoint returned; null on timeout.
created_at	string	When the attempt was made.

Failed deliveries are retried with increasing delay; each retry appears as a new record with a higher attempt. Make handlers idempotent — a slow 2xx can race a retry and produce duplicates.