# 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')

  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