Skip to main content
Webhooks allow you to receive real-time HTTP notifications when events occur in your application, such as incoming messages or delivery status updates.

​
Creating a Webhook

Create a webhook for your application to start receiving event notifications. Via Dashboard
  1. Navigate to your application’s Webhooks page
  2. Click “Create Webhook”
  3. Enter your webhook URL
  4. Select the events you want to receive
  5. (Optional) Add custom headers for authentication
  6. Save the webhook
Via API Use the POST /v1/webhooks endpoint: 
curl -X POST https://api.buildwithchirp.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/chirp",
    "events": ["MESSAGE_CREATED", "MESSAGE_DELIVERED"],
    "headers": {
      "X-Webhook-Secret": "your-secret-key"
    }
  }'

​
Configuration Options

URL The HTTPS endpoint where Chirp will send webhook events. Must be publicly accessible. Events Array of event types to subscribe to:
  • MESSAGE_CREATED - New message created (incoming messages)
  • MESSAGE_SENT - Message sent to carrier
  • MESSAGE_DELIVERED - Message delivered to recipient
Headers (Optional) Custom HTTP headers included with each webhook request. Use this for:
  • Authentication tokens
  • API keys
  • Routing identifiers
Example: 
{
  "X-Webhook-Secret": "your-secret-key",
  "X-App-Id": "your-app-identifier"
}

​
Webhook Delivery

When an event occurs, Chirp sends a POST request to your webhook URL: 
POST /webhooks/chirp HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-Webhook-Secret: your-secret-key

{
  "event": "MESSAGE_CREATED",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": "+15559876543",
    "to": "+15551234567",
    "text": "Hello",
    "type": "SMS",
    "direction": "INBOUND",
    "status": "RECEIVED",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

​
Response Requirements

Your webhook endpoint should:
  1. Respond quickly - Return a 200 OK status within 5 seconds
  2. Process asynchronously - Don’t block the response on long-running tasks
  3. Handle duplicates - Same event may be delivered multiple times
Example response: 
app.post("/webhooks/chirp", (req, res) => {
  // Acknowledge immediately
  res.status(200).send("OK");

  // Process asynchronously
  processWebhook(req.body);
});

​
Retry Behavior

If your webhook fails (non-200 status or timeout):
  • Chirp retries delivery automatically
  • Uses exponential backoff between retries
  • Maximum retry attempts: 5
  • Failed webhooks are logged in your dashboard

​
Security Best Practices

1. Use HTTPS Always use HTTPS URLs for webhook endpoints. HTTP is not supported. 2. Validate Requests Use custom headers to verify requests are from Chirp: 
app.post("/webhooks/chirp", (req, res) => {
  const secret = req.headers["x-webhook-secret"];

  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send("Unauthorized");
  }

  // Process webhook
  res.status(200).send("OK");
});
3. Use IP Allowlisting Restrict webhook access to Chirp’s IP addresses (available in your dashboard).

​
Testing Webhooks

Use the Playground The easiest way to test webhooks is through the Playground:
  1. Configure a webhook on your test application
  2. Use the Playground to send test messages
  3. Your webhook receives events in real-time
  4. View webhook delivery logs in the dashboard
Use Webhook Testing Tools For local development, use tools like:
  • ngrok - Create public URLs for local servers
  • webhook.site - Inspect webhook payloads
  • RequestBin - Debug webhook requests

​
Managing Webhooks

List Webhooks View all webhooks for your application via the dashboard or API: 
curl https://api.buildwithchirp.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_APP_KEY"
Update Webhook Modify webhook configuration: 
curl -X PUT https://api.buildwithchirp.com/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-url.com/webhooks",
    "events": ["MESSAGE_CREATED"]
  }'
Delete Webhook Remove a webhook: 
curl -X DELETE https://api.buildwithchirp.com/v1/webhooks/{webhookId} \
  -H "Authorization: Bearer YOUR_APP_KEY"

​
Troubleshooting

Webhook not receiving events
  • Verify the webhook URL is publicly accessible
  • Check that events are configured correctly
  • Review webhook logs in the dashboard
Webhook timing out
  • Respond with 200 OK immediately
  • Move processing to background jobs
  • Increase server timeout limits
Duplicate events
  • Implement idempotency using the event ID
  • Track processed event IDs to prevent duplicates
⌘I