PUT
/
api
/
v1
/
public
/
webhooks
​
Authorization
string
required

​
Request Body

{
  "webhookConfig": {
    "url": "https://your-webhook-url.com/notifications"
  },
  "inboundWebhookConfig": {
    "url": "https://your-webhook-url.com/inbound"
  }
}

​
Request Fields

​
webhookConfig (Optional)

​
webhookConfig
object
Configuration for notification webhook
​
url
string
required
The URL where notification events will be sent

​
inboundWebhookConfig (Optional)

​
inboundWebhookConfig
object
Configuration for inbound message webhook
​
url
string
required
The URL where inbound messages will be sent

​
Example: cURL Request

curl --location --request PUT 'https://api.trysiren.io/api/v1/public/webhooks' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your-access-token' \
--data-raw '{
  "webhookConfig": {
    "url": "https://your-webhook-url.com/notifications"
  },
  "inboundWebhookConfig": {
    "url": "https://your-webhook-url.com/inbound"
  }
}'

​
Response

​
Success Response (200 OK)

{
  "success": true,
  "message": "Webhook configuration updated successfully",
  "data": {
    "webhookConfig": {
      "url": "https://your-webhook-url.com/notifications"
    },
    "inboundWebhookConfig": {
      "url": "https://your-webhook-url.com/inbound"
    }
  }
}

​
Webhook Payloads

​
Notification Webhook Payload

When a notification event occurs, Siren will send a POST request to the configured webhook URL with the following payload structure: 
{
  "event": "notification.status.updated",
  "timestamp": "2023-01-01T12:00:00Z",
  "data": {
    "notificationId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "delivered",
    "channel": "email",
    "recipient": "user@example.com",
    "metadata": {
      "workflowId": "w-1234567890",
      "templateId": "tpl-1234567890"
    }
  }
}

​
Webhook Headers

Each webhook request will include the following headers:
  • X-Siren-Event: The type of event (e.g., notification.status.updated)
  • X-Siren-Delivery: A unique ID for this webhook delivery
  • X-Siren-Signature: A signature you can use to verify the webhook’s authenticity
  • Content-Type: application/json

​
Error Responses

​
400 Bad Request

{
  "success": false,
  "message": "Invalid request body",
  "errors": [
    "At least one of webhookConfig or inboundWebhookConfig must be provided"
  ]
}

​
401 Unauthorized

{
  "success": false,
  "message": "Unauthorized",
  "error": "Invalid or missing authentication token"
}

​
Best Practices

  1. Always verify the X-Siren-Signature header to ensure the webhook is from Siren
  2. Implement retry logic for handling failed webhook deliveries
  3. Set up appropriate rate limiting on your webhook endpoint
  4. Keep your webhook URL secure and never expose it in client-side code
  5. Handle duplicate events by checking the X-Siren-Delivery header