Webhooks Overview

Webhooks allow you to receive real-time notifications when events occur in your APIMW account.

How Webhooks Work

┌─────────────┐     Event occurs     ┌─────────────┐
│   APIMW     │ ──────────────────► │  Your App   │
│   Platform  │      POST request   │  /webhook   │
└─────────────┘                      └─────────────┘
       │                                    │
       │       200 OK (acknowledge)         │
       │ ◄──────────────────────────────────┘

1. An event occurs (message sent, delivered, etc.)
2. APIMW sends a POST request to your webhook URL
3. Your server processes the event
4. Return 200 OK to acknowledge receipt

Setting Up Webhooks

1. Create a Webhook Endpoint

Your endpoint must:

• Accept POST requests
• Return 200 OK quickly (within 5 seconds)
• Handle duplicate events (idempotency)

2. Register Your Webhook

curl -X POST https://api.apimw.com/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/apimw",
    "events": ["message.sent", "message.delivered", "message.received"],
    "secret": "your_webhook_secret"
  }'

3. Verify Webhook Signatures

Always verify the signature to ensure webhooks are from APIMW.

Retry Policy

If your endpoint fails to respond with 200 OK:

After 5 failed attempts, the webhook is disabled.

Best Practices

1. Respond Quickly - Return 200 OK immediately, process async
2. Handle Duplicates - Events may be sent more than once
3. Verify Signatures - Always validate webhook authenticity
4. Use HTTPS - Webhook URLs must use HTTPS
5. Log Events - Keep logs for debugging