Webhook Events

urelay supports the following webhook event types.

Event types

Event	Description
message.received	A new message was received from a contact
message.sent	An outbound message was confirmed as sent
message.delivered	A sent message was delivered to the recipient
message.read	A sent message was read by the recipient

Payload structure

All events share the same top-level structure:

{
  "event": "message.received",
  "phone_line_id": "cmlsxywe60000qq01704dovyf",
  "message": { ... }
}

message.received

Fired when a new inbound message arrives on one of your phone lines.

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

message.sent

Fired when an outbound message you sent via the API is confirmed as dispatched.

{
  "event": "message.sent",
  "phone_line_id": "cmlsxywe60000qq01704dovyf",
  "message": {
    "id": "cmlt67890000def",
    "guid": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
    "text": "Hello from urelay!",
    "handle": "+12025551234",
    "chatIdentifier": "+12025551234",
    "isFromMe": true,
    "service": "iMessage",
    "isSent": true,
    "isDelivered": false,
    "isRead": false
  }
}

Subscribing to events

When creating or updating a webhook, specify which events you want to receive:

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/webhook",
    "events": ["message.received"]
  }'

You can subscribe to multiple events per webhook or create separate webhooks for different event types.