Webhooks
Create a webhook endpoint
Registers an https URL. The signing secret is returned once and cannot be read again. Every delivery is signed with Raylight-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> and carries Raylight-Event-Id (stable across retries) and Raylight-Event-Type. Failed deliveries retry at 30s, 2m, 10m, 1h and 6h; after 20 exhausted deliveries in a row the endpoint is switched off and the workspace owner emailed.
POST
/v1/webhooksAPI key with the productions scope.
Request body
application/json
| Field | Type | Description |
|---|---|---|
workspaceId | uuid | |
urlrequired | url | |
description | string | |
events | enum[] |
Responses
201The endpoint with its secret.
400Invalid request.
401Missing, invalid or revoked key.
403The key lacks the
productions scope (code api_key_missing_scope), or its owner has view-only access to the workspace (code forbidden).404No such endpoint or workspace for this key (code
not_found).409The workspace has reached its endpoint limit.
429Rate limited, or a monthly cap reached.
503Webhooks are not switched on for this server (code
disabled). Every webhook route answers this while they are off.201 response body
| Field | Type | Description |
|---|---|---|
endpointrequired | object | |
endpoint.idrequired | uuid | |
endpoint.workspaceIdrequired | uuid | |
endpoint.urlrequired | url | |
endpoint.descriptionrequired | string | null | |
endpoint.eventsrequired | enum[] | |
endpoint.enabledrequired | boolean | |
endpoint.disabledReasonrequired | string | null | |
endpoint.consecutiveFailuresrequired | integer | |
endpoint.lastAttemptAtrequired | datetime | null | |
endpoint.lastSuccessAtrequired | datetime | null | |
endpoint.previousSecretExpiresAtrequired | datetime | null | |
endpoint.createdAtrequired | datetime | |
endpoint.updatedAtrequired | datetime | |
endpoint.secretrequired | string |
Example
curl -X POST https://api.raylight.app/v1/webhooks \ -H "Authorization: Bearer $RAYLIGHT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://hooks.acme.dev/raylight", "description": "Slack relay", "events": ["production.pitch_ready", "production.delivered", "production.failed"]}'