> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Setup

> Configure webhooks to receive real-time message notifications

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:

```bash icon="terminal" title="Create Webhook" theme={null}
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": ["messages.sms.sent", "messages.sms.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:

* `messages.sms.received` - Inbound SMS or MMS message received
* `messages.sms.sent` - SMS message sent to carrier
* `messages.sms.delivered` - SMS message delivered to recipient
* `messages.sms.failed` - SMS message delivery failed

**Headers** (Optional)

Custom HTTP headers included with each webhook request. Use this for:

* Authentication tokens
* API keys
* Routing identifiers

Example:

```json theme={null}
{
  "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:

```http theme={null}
POST /webhooks/chirp HTTP/1.1
Host: your-app.com
Content-Type: application/json
X-Webhook-Secret: your-secret-key

{
  "event": "messages.sms.delivered",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": "+15551234567",
    "to": "+15559876543",
    "status": "delivered",
    "deliveredAt": "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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```bash theme={null}
curl https://api.buildwithchirp.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

**Update Webhook**

Modify webhook configuration:

```bash icon="terminal" title="Update Webhook" theme={null}
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": ["messages.sms.delivered"]
  }'
```

**Delete Webhook**

Remove a webhook:

```bash theme={null}
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