Webhooks

Webhooks allow you to receive real-time updates when a specific event occurs, i.e. message is received from a contact. These events are HTTP POST requests being sent to an endpoint of your server. Request body is in JSON format. All events are delivered to a single webhook url (i.e. https://your-server.com/webhook).

When you receive a webhook event, you should always return HTTP response in 2xx class, i.e. 200 OK in shortest time possible. When reply is not 200 OK Smartsupp will try to re-deliver the webhook again later.

Enable Webhooks

Currently we don't have published UI for managing API and webhooks. To enable webhooks please contact our support with your url and required events to subscribe.

Verification

Webhooks can be verified by calculating a HMAC signature. Each webhook request includes a X-Smartsupp-Hmac header, which is generated using the app's shared secret along with the data sent in the request.

Following code can be used to verify webhook request in Node.js (with koa):

import { createHmac } from 'crypto'
import koaBody from 'koa-body'

const UNPARSED_BODY = Symbol.for('unparsedBody')
const secret = 'YOUR_CLIENT_SECRET'

function generateHmac(secret, body) {
  return createHmac('sha256', secret).update(body).digest('hex')
}

router.use(koaBody({
  includeUnparsed: true, // required to returns raw body as string
}))
router.use((ctx, next) => {
  if (ctx.headers['x-smartsupp-hmac'] !== generateHmac(secret, ctx.request.body[UNPARSED_BODY])) {
    ctx.throw(403, 'Invalid request hmac signature')
  }
  return next()
})

Structure

All webhooks have following body structure:

{
  "type": "event_callback",
  "event": "<name>",
  "timestamp": "2020-08-08T07:53:18.825Z",
  "account_id": "881987",
  "app_id": "ap40qUkYi",
  "data": {
    ...
  }
}

Property	Type	Description
type	string	All events will have always value "event_callback".
event	string	Name of the event (eg: "conversation.closed").
timestamp	string	ISO date format of date when event was created.
account_id	string	Identifies account.
app_id	string	Identifies specific integration.
data	object	Event related data.

Events

Name	Description