API Reference · Webhooks

Create webhook

Subscribe an endpoint to delivery events. The signing secret is returned once, on creation.

POST/v1/webhooks

Headers

Authorizationstringrequired

Your API key as a bearer token: Bearer rk_your_api_key. You can also use the X-Api-Key header.

Body parameters

urlstringrequired

An absolute HTTPS URL to receive events.

eventTypesstring[]optional

Event types to subscribe to. Omit or empty for all events.

Request

curl -X POST https://api.raanse.com/v1/webhooks \
  -H "Authorization: Bearer rk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://acme.co/webhooks/ranse",
        "eventTypes": [
          "Delivered",
          "Bounced"
        ]
      }'

Response

201

{
  "success": true,
  "message": "Resource created",
  "statusCode": 201,
  "data": {
    "id": "01JABCDXYZ0000000000000000",
    "url": "https://acme.co/webhooks/ranse",
    "enabled": true,
    "eventTypes": ["Delivered", "Bounced"],
    "signingSecret": "whsec_shown_once",
    "createdAt": "2026-07-02T12:00:00Z"
  }
}