Skip to main content

Webhooks Overview

Webhooks deliver real-time notifications to your application when events occur in urelay, such as receiving a new message or confirming delivery.

How webhooks work​

  1. You register a webhook endpoint URL and select which events to subscribe to
  2. When a subscribed event occurs, urelay sends an HTTP POST request to your URL
  3. Your endpoint processes the payload and returns a 2xx status code
  4. If delivery fails, urelay retries with exponential backoff

Creating a webhook​

curl -X POST https://app.urelay.ai/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ur_live_YOUR_KEY" \
  -H "X-API-Secret: ur_secret_YOUR_SECRET" \
  -d '{
    "url": "https://your-app.com/webhooks/urelay",
    "events": ["message.received", "message.sent"]
  }'

The response includes a secret field -- this is your signing secret for verifying that webhook payloads genuinely come from urelay. Store it securely; it is only shown once.

Webhook payload format​

All webhook deliveries are HTTP POST requests with a JSON body:

{
  "event": "message.received",
  "phone_line_id": "cmlsxywe60000qq01704dovyf",
  "message": {
    "id": "cmlt12345000abc",
    "guid": "6EEC3F64-A2B1-4C8F-9B2D-1234567890AB",
    "text": "Hey, got your message!",
    "handle": "+12025551234",
    "chatIdentifier": "+12025551234",
    "isFromMe": false,
    "service": "iMessage",
    "isSent": true,
    "isDelivered": true,
    "isRead": false
  }
}

Managing webhooks​

You can update or delete webhooks via the API or the dashboard:

  • Update: PUT /api/v1/webhooks/{id} -- change URL, events, or active status
  • Delete: DELETE /api/v1/webhooks/{id} -- remove a webhook endpoint
  • Pause: Update with is_active: false to temporarily stop deliveries

Best practices​

  • Always verify webhook signatures before processing payloads
  • Return 200 quickly and process the payload asynchronously
  • Use a dedicated URL path for urelay webhooks
  • Monitor delivery logs in the dashboard for failures