​
Inbound Message Webhook

The Inbound Message Webhook allows your application to receive and process messages sent by users through various communication channels like SMS, WhatsApp, Slack, etc. When a user sends a message to a number or channel that’s configured with Siren, the message is forwarded to your configured webhook URL.

​
Webhook Configuration

To set up the inbound message webhook, configure the inboundWebhookConfig.url using the Update Webhook Configuration API.

​
Webhook Payload

When an inbound message is received, Siren will send a POST request to your configured webhook URL with the following payload structure: 
{
  "event": "message.received",
  "timestamp": "2023-01-01T12:00:00Z",
  "channel": "whatsapp",
  "message": {
    "id": "msg_1234567890",
    "from": "+1234567890",
    "to": "+1987654321",
    "text": "Hello, I have a question about my order",
    "timestamp": "2023-01-01T12:00:00Z",
    "media": [
      {
        "type": "image",
        "url": "https://example.com/media/image.jpg",
        "caption": "Product image"
      }
    ]
  },
  "metadata": {
    "provider": "twilio",
    "channelSid": "CHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "messageSid": "IMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

​
Payload Fields

​
Event Information

​
event
string
required
The type of event. For inbound messages, this will be message.received.
​
timestamp
string
required
The timestamp when the event occurred.
​
channel
string
required
The channel through which the message was received (e.g., whatsapp, sms, slack).

​
Message Object

​
message
object
required
Contains the details of the received message.
​
id
string
required
A unique identifier for the message.
​
from
string
required
The sender’s identifier (phone number, user ID, etc.).
​
to
string
required
The recipient’s identifier (phone number, channel ID, etc.).
​
text
string
The message text content, if any.
​
timestamp
string
required
The timestamp when the message was sent by the user.
​
media
array
Array of media objects if the message contains media (images, documents, etc.).
​
type
string
required
The type of media (e.g., image, document, audio).
​
url
string
required
URL to download the media file.
​
caption
string
Caption or description of the media, if provided.

​
Metadata

​
metadata
object
required
Additional metadata about the message.
​
provider
string
required
The provider that delivered the message (e.g., twilio, messagebird).
​
channelSid
string
The channel SID or ID from the provider.
​
messageSid
string
The message SID or ID from the provider.

​
Webhook Headers

Each webhook request will include the following headers:
​
X-Siren-Event
string
required
The type of event (e.g., message.received).
​
X-Siren-Delivery
string
required
A unique ID for this webhook delivery. Use this for idempotency.
​
X-Siren-Signature
string
required
A signature you can use to verify the webhook’s authenticity.
​
Content-Type
string
required
Will always be application/json.

​
Webhook Response

Your webhook endpoint should return a 200 OK status code within 3 seconds to acknowledge receipt of the webhook. If Siren doesn’t receive a successful response, it will retry the webhook delivery according to the retry policy.

​
Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true
}

​
Error Response (Optional)

If you want to return an error message to the sender, you can include it in the response: 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "The request could not be processed"
  }
}

​
Webhook Retry Policy

If your webhook endpoint returns an error (non-2xx status code) or times out, Siren will retry delivery with exponential backoff according to the following schedule:
  1. First retry: 1 minute after first failure
  2. Second retry: 3 minutes after first retry
  3. Third retry: 10 minutes after second retry
  4. Fourth retry: 30 minutes after third retry
  5. Final retry: 1 hour after fourth retry
If all retry attempts fail, the message will be discarded.

​
Security

​
Verifying Webhook Signatures

To verify that incoming webhooks are from Siren, verify the X-Siren-Signature header. The signature is generated using HMAC-SHA256 with your webhook signing secret. 
const crypto = require('crypto');

function verifySignature(secret, payload, signature) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'utf8'),
    Buffer.from(digest, 'utf8')
  );
}

​
Best Practices

  1. Verify Signatures: Always verify the X-Siren-Signature header to ensure the webhook is from Siren.
  2. Idempotency: Use the X-Siren-Delivery header to prevent processing duplicate events.
  3. Timeouts: Process webhooks quickly and respond within 3 seconds to avoid timeouts.
  4. HTTPS: Always use HTTPS for your webhook endpoints to ensure data security.
  5. Rate Limiting: Implement rate limiting to protect your webhook endpoint from abuse.
  6. Logging: Log all incoming webhook requests for debugging and auditing purposes.