Webhook Configuration

Register the URLs that AfriRoute should call and choose which events each endpoint receives. You can manage webhooks from the dashboard or programmatically through the API documented below.

🚀 Quick Start

curl -X POST https://api.afriroute.ai/api/v1/webhooks \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhook",
    "events": ["sms.delivered", "payment.completed"],
    "description": "Production events"
  }'

📡 Endpoints

Method	Path	Description
POST	/v1/webhooks	Create a webhook
GET	/v1/webhooks	List all webhooks
GET	/v1/webhooks/:id	Retrieve a webhook
PATCH	/v1/webhooks/:id	Update URL, events, or status
DELETE	/v1/webhooks/:id	Delete a webhook
POST	/v1/webhooks/:id/test	Send a test event

Create Webhook — Parameters

Field	Type	Required	Description
url	string	Yes	HTTPS endpoint to receive events
events	array	Yes	Event types to subscribe to (use ["*"] for all)
description	string	No	Human-readable label
enabled	boolean	No	Whether the webhook is active (default true)

💻 Code Samples

Node.js — create

const res = await fetch('https://api.afriroute.ai/api/v1/webhooks', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url: 'https://yourapp.com/webhook',
    events: ['sms.delivered', 'sms.failed', 'payment.completed']
  })
});
const webhook = await res.json();
console.log(webhook.id, webhook.secret);

Python — list

import requests
res = requests.get(
    'https://api.afriroute.ai/api/v1/webhooks',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'}
)
for wh in res.json()['data']:
    print(wh['id'], wh['url'], wh['enabled'])

📊 Response

{
  "id": "wh_5k2j9",
  "url": "https://yourapp.com/webhook",
  "events": ["sms.delivered", "payment.completed"],
  "secret": "whsec_4a1b2c3d4e5f6071",
  "enabled": true,
  "created_at": "2026-05-10T09:00:00Z"
}

Store the secret immediately

The secret is returned only once at creation. Save it securely — you will need it to verify signatures. If lost, rotate it from the dashboard.

🧪 Testing an Endpoint

curl -X POST https://api.afriroute.ai/api/v1/webhooks/wh_5k2j9/test \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

This delivers a sample event so you can confirm your endpoint is reachable and verifies signatures correctly. For local development, expose your server with a tunnel such as ngrok.

💡 Best Practices

• Use separate endpoints for production and sandbox environments.
• Subscribe only to events you handle to reduce noise and load.
• Disable rather than delete a webhook while debugging to preserve its secret.
• Rotate the signing secret periodically and on any suspected leak.
• Monitor delivery health in the dashboard and alert on rising failure rates.

⚠️ Error Handling

Code	HTTP	Description
INVALID_URL	400	URL is not a valid HTTPS endpoint
INVALID_EVENT	400	One or more event types are unknown
WEBHOOK_LIMIT_REACHED	422	Plan webhook limit exceeded
WEBHOOK_NOT_FOUND	404	No webhook with that ID

See the error code reference for the full list.

📚 Related Resources

• Webhooks Overview
• Webhook Security
• Webhook Events
• Retry Logic

---

Last Updated: May 2026 | Need help? [email protected]