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

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

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

3. 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.

4. Here's how an example configuration of enabling status updates for email notification looks like:

Form Fields and their descriptions:

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"
}