Skip to main content

Webhooks

Register and manage a single webhook subscription per organization to receive real-time events. All endpoints use API-key authentication and the standard response envelope — see Getting Started for x-api-key, base URL, and rate limits. For the full event catalog and receiver examples, see Webhook Events.

Get Webhook Configuration​

GET /v1/webhooks
curl -X GET 'https://app.superwaba.com/api/developer/v1/webhooks' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response - 200 OK​

{
  "success": true,
  "data": {
    "webhook": {
      "id": "wh_a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "url": "https://your-server.com/webhooks/superginie",
      "events": [
        "message.received",
        "message.sent",
        "message.delivered",
        "message.read",
        "message.failed",
        "contact.created",
        "contact.updated",
        "conversation.opened",
        "conversation.closed"
      ],
      "status": "active",
      "secret": "whsec_abc123..."
    }
  }
}

Register or Update Webhook​

POST /v1/webhooks
curl -X POST 'https://app.superwaba.com/api/developer/v1/webhooks' \
  -H 'x-api-key: sgk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://your-server.com/webhooks/superginie",
  "events": ["message.received", "message.sent", "conversation.closed"],
  "signing_secret": "whsec_your_secret"
}'

Request Body​

{
  "url": "https://your-server.com/webhooks/superginie",
  "events": [
    "message.received",
    "message.sent",
    "message.delivered",
    "message.read",
    "message.failed",
    "contact.created",
    "contact.updated",
    "conversation.opened",
    "conversation.closed"
  ],
  "signing_secret": "whsec_your_secret"
}
ParameterTypeRequiredDescription
urlstringYesHTTPS URL to receive webhook POST events
eventsstring[]YesArray of event types to subscribe to
signing_secretstringNoSecret sent as X-Webhook-Secret header for verification

Response - 200 OK​

{
  "success": true,
  "data": {
    "webhook": {
      "id": "wh_a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "url": "https://your-server.com/webhooks/superginie",
      "events": ["message.received", "message.sent", "conversation.closed"],
      "status": "active"
    }
  }
}

Response - 400 Invalid URL​

{
  "success": false,
  "message": "Webhook URL must use HTTPS"
}

Remove Webhook​

DELETE /v1/webhooks
curl -X DELETE 'https://app.superwaba.com/api/developer/v1/webhooks' \
  -H 'x-api-key: sgk_YOUR_API_KEY'

Response - 200 OK​

{
  "success": true,
  "message": "Webhook removed"
}

Webhook Events for API Messages​

When you send a message via the Developer API, a message.sent webhook event is dispatched (if you have an active webhook subscription).

Instagram text message sent via API:

{
  "event": "message.sent",
  "timestamp": "2026-05-26T14:30:00.000Z",
  "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": {
    "channel": "instagram",
    "message_id": "mid.$cAAJsb3ADKF2mBRdvalgzRb3RNIHR",
    "to": "17841400000000000",
    "type": "text",
    "content": {
      "text": "Hello from the API!"
    },
    "status": "sent",
    "timestamp": "2026-05-26T14:30:00.000Z"
  }
}

Messenger carousel sent via API:

{
  "event": "message.sent",
  "timestamp": "2026-05-26T14:30:00.000Z",
  "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": {
    "channel": "messenger",
    "message_id": "mid.YYYY",
    "to": "1234567890",
    "type": "generic_template",
    "content": {
      "attachment": {
        "type": "template",
        "payload": {
          "template_type": "generic",
          "elements": [
            {
              "title": "Product A",
              "subtitle": "Best seller - $29",
              "image_url": "https://example.com/a.jpg",
              "buttons": [
                { "type": "web_url", "title": "Buy Now", "url": "https://example.com/a" }
              ]
            }
          ]
        }
      }
    },
    "status": "sent",
    "timestamp": "2026-05-26T14:30:00.000Z"
  }
}

WhatsApp template sent via API:

{
  "event": "message.sent",
  "timestamp": "2026-05-26T14:30:00.000Z",
  "webhook_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "data": {
    "channel": "whatsapp",
    "message_id": "wamid.HBgLMTIzNDU2Nzg5MBUCABIYZ...",
    "to": "919876543210",
    "type": "template",
    "content": {
      "template": {
        "name": "order_update",
        "language": "en"
      }
    },
    "status": "sent",
    "timestamp": "2026-05-26T14:30:00.000Z"
  }
}

See Webhook Events for the full list of events, payload formats, and the Express.js/Python server examples.