Relay SMS Platform
Relay SMS API

Webhooks

Endpoint

Configure HTTP endpoints for event notifications

List webhooks

GET
https://api.relay.works
/v1/webhooks

List webhooks › Responses

List of webhooks

  • idstring · uuid
  • workspace_idstring · uuid
  • urlstring · uri
  • eventsstring[]
    Enum values:
    message.sent
    message.delivered
    message.failed
    message.status.updated
  • created_atstring · date-time
  • updated_atstring · date-time

Create webhook

POST
https://api.relay.works
/v1/webhooks

Register a webhook endpoint to receive event notifications.

The response includes signing_secret — a per-webhook HMAC secret returned exactly once. Store it immediately; GET /v1/webhooks responses do not include it. Use it to verify the Relay-Signature header on incoming deliveries. See the webhook security guide.

Create webhook › Request Body

  • urlstring · uri · required

    HTTPS endpoint to deliver events to. Must not resolve to a private network.

  • eventsstring[] · minItems: 1 · required
    Enum values:
    message.sent
    message.delivered
    message.failed
    message.status.updated
    Example: ["message.status.updated"]

Create webhook › Responses

Webhook created. The signing_secret field is returned only in this response.

  • idstring · uuid
  • workspace_idstring · uuid
  • urlstring · uri
  • eventsstring[]
    Enum values:
    message.sent
    message.delivered
    message.failed
    message.status.updated
  • created_atstring · date-time
  • updated_atstring · date-time
  • signing_secretstring

    HMAC-SHA256 signing secret for this webhook. Returned exactly once at create / rotate time.

    Example: whsec_3a7b1f9c4d2e8b6a5c0d9e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b
  • signing_secret_warningstring

    Human-readable reminder that this is a one-shot value.

Update webhook

PUT
https://api.relay.works
/v1/webhooks/{id}

Update webhook › path Parameters

  • idstring · uuid · required

Update webhook › Request Body

  • urlstring · uri · required

    HTTPS endpoint to deliver events to. Must not resolve to a private network.

  • eventsstring[] · minItems: 1 · required
    Enum values:
    message.sent
    message.delivered
    message.failed
    message.status.updated
    Example: ["message.status.updated"]

Update webhook › Responses

Webhook updated

  • idstring · uuid
  • workspace_idstring · uuid
  • urlstring · uri
  • eventsstring[]
    Enum values:
    message.sent
    message.delivered
    message.failed
    message.status.updated
  • created_atstring · date-time
  • updated_atstring · date-time

Delete webhook

DELETE
https://api.relay.works
/v1/webhooks/{id}

Delete webhook › path Parameters

  • idstring · uuid · required

Delete webhook › Responses

Webhook deleted

No data returned

Rotate webhook signing secret

POST
https://api.relay.works
/v1/webhooks/{id}/rotate-secret

Invalidate the current signing secret and return a new one. In-flight deliveries signed with the prior secret will fail verification on the consumer side once the new secret is in effect. Plan rotations during low-traffic windows.

Rotate webhook signing secret › path Parameters

  • idstring · uuid · required

Rotate webhook signing secret › Responses

New signing secret issued. Returned only in this response.

  • idstring · uuid
  • workspace_idstring · uuid
  • urlstring · uri
  • eventsstring[]
    Enum values:
    message.sent
    message.delivered
    message.failed
    message.status.updated
  • created_atstring · date-time
  • updated_atstring · date-time
  • signing_secretstring

    HMAC-SHA256 signing secret for this webhook. Returned exactly once at create / rotate time.

    Example: whsec_3a7b1f9c4d2e8b6a5c0d9e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b
  • signing_secret_warningstring

    Human-readable reminder that this is a one-shot value.

Send test webhook

POST
https://api.relay.works
/v1/webhooks/{id}/test

Send a synthetic test payload to the configured webhook URL.

Send test webhook › path Parameters

  • idstring · uuid · required

Send test webhook › Responses

Test attempt completed (success may still be false)

  • successboolean
  • status_codeinteger | null
  • messagestring
  • deliveryobject

List webhook delivery attempts

GET
https://api.relay.works
/v1/webhooks/{id}/deliveries

Returns a bare array of delivery records (not a { data, pagination } envelope). The page and limit parameters control the range query but the response does not include pagination metadata.

List webhook delivery attempts › path Parameters

  • idstring · uuid · required

List webhook delivery attempts › query Parameters

  • pageinteger
    Default: 1
  • limitinteger

    Items per page. Defaults to 50 (higher than the standard 20) because delivery logs are typically scanned in bulk during debugging.

    Default: 50

List webhook delivery attempts › Responses

Delivery log entries

  • idstring · uuid

    Unique delivery attempt identifier.

  • webhook_idstring · uuid
  • eventstring · enum
    Enum values:
    message.sent
    message.delivered
    message.failed
    message.status.updated
    test.webhook.sent
  • status_codeinteger | null

    HTTP response code, or null if the request failed at the network layer.

  • response_bodystring

    Truncated response body (max 1000 chars).

  • delivered_atstring · date-time
  • testboolean | null
Phone NumbersAnalytics