Register webhooks

Before receiving webhook events you need to register your endpoint and tell us the topic you would like to subscribe to and the address where we send the events. For example:

cURL

curl --request POST \
     --url https://api.connectly.ai/v1/businesses/<business_id>/create/webhooks \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: <YOUR_KEY_HERE>' \
     --data '
{
    "topic":"messages",
    "address":"https://example.com/webhook"
}'

There are 2 topics for webhook events:

• messages: responses from clients including messages and button responses.
• delivery_status: WhatsApp delivery status updates that indicate whether your messages have reached the customers or not.

As an example, a webhook event may look like the following:

JSON

// Headers:
{
  "content-length": "154",
  "x-connectly-hmac-sha256": "OS/QJB97O/sOj3Ugh4vUJ32EE2++vWq9o51ajIJZwuo=",
  "user-agent": "go-resty/2.6.0 (https://github.com/go-resty/resty)",
  "content-type": "text/plain; charset=utf-8",
  "accept-encoding": "gzip"
}
// Body
{
  "timestamp": "1639083206",
  "sender": {
    "id": "[phone]",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "123456123",
    "channelType": "whatsapp"
  },
  "message": {
    "text": "TEST 11"
  }
}

The webhook request header contains HMAC Sha256 to verify that the event comes from Connectly. The HMAC can be found in the header x-connectly-hmac-sha256. Below are examples on how to verify the HMAC:

Go

secret := "YOUR_SECRET_VALUE"   
data := string(webhookEventBody)
hash := hmac.New(sha256.New, []byte(secret))
_, err := hash.Write(data)
if err != nil {
    return "", err
}
isValid := webhookEventHMAC == base64.StdEncoding.EncodeToString(hash.Sum(nil)), nil

JavaScript

const crypto = require("crypto");

app.post('/webhooks', function(req, res) {
    const secret = "YOUR_SECRET_VALUE"
    const retrievedSignature = req.get("x-connectly-hmac-sha256")
    const bodyString = Buffer.from(req.rawBody, 'utf8')

    hash = crypto.createHmac("sha256", secret).update(bodyString).digest("base64");
    if (hash === retrievedSignature) {
            res.send(200);
    }
        res.send(403);
});

JavaScript has express-middleware that can do this for you: https://github.com/neeler/express-verify-hmac-signature.

To acknowledge delivery on your end your endpoint needs to reply with 200 response.