Outbound Webhook

You can use webhook to get real-time notification updates in your application. SuprSend processes data received from your end-vendors in a standard format, so you don't have to adapt your system for different vendor data structures.

How it works?

SuprSend sends a JSON payload to a specified endpoint (URL) as soon as a notification update is received, for example when a message is sent, delivered, seen or replied by user. You can configure which events you want to receive on a particular endpoint, allowing you to filter out unnecessary data and only receive the information relevant to your application. Once the data is received, a POST request is sent to the endpoint you've provided. You can then use it to store information or trigger specific actions in your app.

Getting Started

1. Create an endpoint in your application to receive webhook requests

Create an endpoint in your application specifically to receive webhook requests from SuprSend. The endpoint should be an HTTP or HTTPS URL. Once you have created the endpoint, configure it in SuprSend dashboard to receive notification updates. You can use one endpoint per event type or you can send multiple types of events to the same endpoint.

📘
Currently supported in Whatsapp and SMS
We are currently providing the webhook support for whatsapp & SMS channel. Support for other channels will be rolled out soon.

2. Add the endpoint in SuprSend dashboard and start receiving events

Navigate to the settings page on SuprSend dashboard and go to Webhooks section. On the webhooks page, click on "Enable Webhook"

Once you have enabled webhook, you'll see a screen like below. Click on "Add Endpoint"

This will open endpoint settings form. Add the endpoint URL that you have created in the first step and give it a description for your reference. Select the event type that you want to receive on this endpoint for each channel.

Form Fields and their descriptions:

Field	Obligation	Description
URL	mandatory	http or https endpoint where you want to receive the webhook requests from SuprSend. Must support POST method and content-type should be application/json
Description	optional	add the reference of what information will be tracked in the given endpoint
Event type	mandatory	What all events should be tracked in this endpoint at each channel level. In case of whatsapp, inbound_message = all requests related to user responses and status = notification status such as sent, delivered, seen etc.
Advanced Configuration -> Rate Limit	optional	Number of webhook requests that you want to receive per second on the given endpoint. After the limit is reached, requests will get throttled so to keep a consistent rate under the limit.
Advanced Configuration -> Custom Headers	optional	You'll be able to add custom headers after saving the webhook endpoint. `Content-type = application/json` is set by default. You can use this field to set authentication token in SuprSend request

Webhook Payload Structure

This is an example of the webhook payload structure. The payload contains normalized data from SuprSend as well as the vendor response received. The payload structure will be similar for all channels except for vendor response. Vendor response will contain the exact vendor response received from the vendors and will vary based on the structure of vendor response.

Sample payload for Whatsapp Status

{
  "channel": "whatsapp",
  "channel_value": "+15555555555",
  "distinct_id": "[email protected]",
  "event_type": "status",
  "reference": {
    "idempotency_key": "44220630-d9ae-49f2-918e-0b2f6018cecf",
    "supr_execution_id": "01GNEQZ65HRWZP5H0JY0TQA9VG",
    "supr_ngid": "01GNEQZ6F2DE7BF0AFTXWZE7AE",
    "supr_nid": "01GNEQZ6F4JZF1BAK9CDXYD4T4",
    "vendor_ack_id": "4804988740932718661-lap5NefpkeN4gKyi8CiM-01GNEQZ6F4JZF1BAK9CDXYD4T4",
    "workspace_name": "staging",
    "workspace_uid": "lap5XXXXXXXXXXX"
  },
  "suprsend_status": {
    "status": "delivered",
    "timestamp": 1672310923000
  },
  "template": "purchase-made",
  "vendor_name": "gupshup",
  "vendor_response": {
    "gupshup": {
      "event_type": "status",
      "response": [
        {
          "cause": "SUCCESS",
          "channel": "WHATSAPP",
          "destAddr": "15555555555",
          "errorCode": "000",
          "eventTs": 1672310923000,
          "eventType": "DELIVERED",
          "externalId": "4804988740932718661-lap5NefpkeN4gKyi8CiM-01GNEQZ6F4JZF1BAK9CDXYD4T4",
          "extra": "",
          "srcAddr": "TESTSM"
        }
      ]
    }
  },
  "version": "1.0",
  "workflow_name": "Purchase Made"
}

Webhook Payload Structure for 2 way communication

This is an example of the webhook payload structure for consuming user replies and sending further notifications based on the response structure. You'll get user replies in suprsend_inbound_message json in the webhook response. The payload contains normalized data from SuprSend as well as the vendor response received.

Sample payload for Whatsapp User reply

{
  "channel": "whatsapp",
  "channel_value": "+15555555555",
  "distinct_id": "[email protected]",
  "event_type": "inbound_message",
  "reference": {
    "idempotency_key": "a29a7a15-7a02-400b-8257-2220750b11b3",
    "supr_execution_id": "01H08212H17MMW152F370TM4FT",
    "supr_ngid": "01H08212QBEN2Q2E0XHNPK0NBF",
    "supr_nid": "01H08212QETNQ7J71B42V3XVKD",
    "vendor_ack_id": "4902186086570803293-kfWdrPL1nFqs7OUihiBn-01H08212QETNQ7J71B42V3XVKD",
    "workspace_name": "staging",
    "workspace_uid": "lap5XXXXXXXXXXX"
  },
  "suprsend_inbound_message": {
    "context": {
      "from": "+14444444444",
      "id": "gBEGkZMmKUh5AglyguZOxeyE6Xc"
    },
    "from": "+15555555555",
    "message_type": "quoted",
    "source_message_id": "lap5XXXXXXXXXXX-01H08212QETNQ7J71B42V3XVKD",
    "source_message_sent_via_suprsend": true,
    "text": {
      "body": "Hi"
    },
    "timestamp": 1683898377000,
    "to": "+14444444444",
    "type": "text"
  },
  "template": "purchase-done",
  "vendor_name": "gupshup",
  "vendor_response": {
    "gupshup": {
      "context": "{\"from\":\"+14444444444\",\"id\":\"gBEGkZMmKUh5AglyguZOxeyE6Xc\"}",
      "messageId": "lap5XXXXXXXXXXX-01H08212QETNQ7J71B42V3XVKD",
      "mobile": "+15555555555",
      "name": "Joe",
      "replyId": "4902186086570803293",
      "text": "Hi",
      "timestamp": "1683898377000",
      "type": "text",
      "waNumber": "+14444444444"
    }
  },
  "version": "1.0",
  "workflow_name": "Purchase Done"
}