Skip to main content
PUT
/
api
/
v1
/
public
/
webhooks
Update Webhook Configuration
curl --request PUT \
  --url https://api.example.com/api/v1/public/webhooks \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "webhookConfig": {
    "url": "<string>"
  },
  "inboundWebhookConfig": {
    "url": "<string>"
  }
}
'
​
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)

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "environment": "PRODUCTION", 
  "webhookConfig": {
    "url": "https://your-webhook-url.com/notifications",
    "headers": [
      {
        "name": "Custom-Header",
        "value": "custom-value"
      }
    ],
    "verificationKey": "webhook-secret-key"
  },
  "inboundWebhookConfig": {
    "url": "https://your-webhook-url.com/inbound",
    "headers": [],
    "verificationKey": "inbound-secret-key"
  }
}

​
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": "[email protected]",
    "metadata": {
      "workflowId": "w-1234567890",
      "templateId": "tpl-1234567890"
    }
  }
}

​
Webhook Headers

Each webhook request will include the following headers:
  • x-siren-webhook-signature: A signature you can use to verify the webhook’s authenticity.
  • Content-Type: application/json (set by HTTP client)
  • Any custom headers configured in your webhook configuration.

​
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.