Webhooks

{
  "event": "qualification.created",
  "timestamp": "2026-05-26T15:30:00Z",
  "companyId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "data": {
    "clientId": "64f1a2b3c4d5e6f7a8b9c0d1",
    "wokuId": "64d4e5f6a7b8c9d0e1f2a3b4",
    "qualification": 5,
    "responseChannel": "review-app"
  }
}

{
  "event": "nps_submission.created",
  "timestamp": "2026-05-26T15:30:00Z",
  "companyId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "data": {
    "npsId": "64b2c3d4e5f6a7b8c9d0e1f2",
    "npsToolId": "64c3d4e5f6a7b8c9d0e1f2a3",
    "responseChannel": "whatsapp"
  }
}

{
  "event": "form_submission.created",
  "timestamp": "2026-05-26T15:30:00Z",
  "companyId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "data": {
    "formResponseId": "64b2c3d4e5f6a7b8c9d0e1f2",
    "formId": "64c3d4e5f6a7b8c9d0e1f2a3",
    "responseChannel": "api"
  }
}

import crypto from 'node:crypto';

function verifyWokuSignature(rawBody, signatureHeader, secret) {
  // signatureHeader: "sha256=<hex>"
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');

  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Example with Express. Use the raw body, not the parsed JSON.
import express from 'express';
const app = express();

app.post(
  '/webhooks/woku',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header('X-Woku-Signature') ?? '';
    if (!verifyWokuSignature(req.body, signature, process.env.WOKU_WEBHOOK_SECRET)) {
      return res.status(401).send('Invalid signature');
    }
    const event = JSON.parse(req.body.toString('utf8'));
    // ... process the event
    res.status(200).json({ received: true });
  },
);

import hashlib
import hmac

def verify_woku_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    # signature_header: "sha256=<hex>"
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)


# Example with Flask. request.data is the raw body.
from flask import Flask, request, abort, jsonify
import os

app = Flask(__name__)

@app.post("/webhooks/woku")
def woku_webhook():
    signature = request.headers.get("X-Woku-Signature", "")
    if not verify_woku_signature(request.data, signature, os.environ["WOKU_WEBHOOK_SECRET"]):
        abort(401)
    event = request.get_json()
    # ... process the event
    return jsonify(received=True), 200

<?php
function verify_woku_signature(string $rawBody, string $signatureHeader, string $secret): bool
{
    // $signatureHeader: "sha256=<hex>"
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WOKU_SIGNATURE'] ?? '';
$secret = getenv('WOKU_WEBHOOK_SECRET');

if (!verify_woku_signature($rawBody, $signature, $secret)) {
    http_response_code(401);
    echo 'Invalid signature';
    exit;
}

$event = json_decode($rawBody, true);
// ... process the event

http_response_code(200);
header('Content-Type: application/json');
echo json_encode(['received' => true]);