Webhooks — Real-time notifications of each signature's status.

Four steps from the event to your server's response

The Webhooks system at Wthaiq is simple and robust: you register a single address that receives the events you care about, and we take care of sending them signed whenever something changes. No polling and no repeated querying — the event reaches you as soon as it occurs.

curl -X POST https://wthaiq.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/hooks/wthaiq",
    "enabled_events": ["signature_request.completed", "signer.signed"]
  }'

{
  "id": "we_1a",
  "object": "webhook_endpoint",
  "url": "https://api.acme.com/hooks/wthaiq",
  "enabled_events": ["signature_request.completed", "signer.signed"],
  "status": "enabled",
  "secret": "whsec_7bK2c8Vd1QpN9sR4tHmZ0xY",   // Shown once — store it securely
  "created_at": 1754000000
}

POST /hooks/wthaiq HTTP/1.1
Host: api.acme.com
Content-Type: application/json
Wthaiq-Version: 2026-07-01
Wthaiq-Signature: t=1754500000,v1=6ff7d3f2b1a0c9e4d5f8a1b0c3a...

{"id":"evt_2M8kQ1","object":"event","type":"signature_request.completed", ... }

All event types and when they fire

Events fall into groups: events at the signature request level signature_request.*, and events for each signer signer.*, alongside the document sealing and public verification events. Subscribe only to what you need through enabled_events.

The event envelope and the affected object

The body of every Webhook request is an object event A single envelope that wraps the affected object under data.object. The field type indicates the event type, and livemode distinguishes live mode from test mode, and created_at is a Unix timestamp (in seconds).

{
  "id": "evt_...",
  "object": "event",
  "type": "signature_request.completed",
  "created_at": 1754500000,
  "livemode": true,
  "data": {
    "object": { /* Affected object: signature_request, signer, or ... */ }
  }
}

{
  "id": "evt_2M8kQ1",
  "object": "event",
  "type": "signature_request.completed",
  "created_at": 1754500000,
  "livemode": true,
  "data": {
    "object": {
      "id": "sr_3n8Kd2Qa1V",
      "object": "signature_request",
      "livemode": true,
      "status": "completed",
      "title": "Employment contract — Ahmed M.",
      "legal_level": "aes",
      "format": "pades-lt",
      "source": { "type": "template", "template_id": "tpl_employment" },
      "signers": [
        {
          "id": "sgr_9fA2",
          "object": "signer",
          "name": "Ahmed Mohamed",
          "email": "ahmed@example.com",
          "type": "individual",
          "method": "draw",
          "require_identity": true,
          "order": 1,
          "status": "signed",
          "signing_url": "https://wthaiq.com/sign.php?token=uZ8..",
          "viewed_at": 1754000100,
          "signed_at": 1754499900,
          "identity": { "status": "approved", "provider": "external", "level": "aes" },
          "fields": { "job_title": "Software engineer", "start_date": "2026-08-01" }
        }
      ],
      "ordered": true,
      "require_identity": true,
      "reference": "WTQ-1A2B3C4D5E6F",
      "reminders": { "enabled": true, "interval_hours": 48, "max": 3 },
      "expires_at": 1755000000,
      "completed_at": 1754500000,
      "download_url": "https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/download",
      "metadata": { "order_id": "A-1024" },
      "created_at": 1754000000
    }
  }
}

Verify every request before trusting it

With every request Wthaiq sends the header Wthaiq-Signature It lets you confirm that the payload came from us and has not been tampered with. Verification is mandatory: do not process any payload before it succeeds.

Verification steps

Implementing verification

const express = require('express');
const crypto  = require('crypto');
const app = express();

const SECRET = process.env.WTHAIQ_WEBHOOK_SECRET; // whsec_...
const TOLERANCE = 300; // seconds

// Important: receive the raw body (Buffer), not parsed JSON
app.post('/hooks/wthaiq',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const raw    = req.body;                       // Raw Buffer
    const header = req.get('Wthaiq-Signature') || '';

    // 1) Extract t and v1
    const parts = Object.fromEntries(
      header.split(',').map(p => p.split('=')));
    const t = parts.t, v1 = parts.v1;

    // 2) Timestamp window (5 minutes)
    const now = Math.floor(Date.now() / 1000);
    if (!t || Math.abs(now - Number(t)) > TOLERANCE)
      return res.status(400).send('timestamp out of tolerance');

    // 3) Recompute the HMAC over "{t}.{raw_body}"
    const signedPayload = t + '.' + raw.toString('utf8');
    const expected = crypto
      .createHmac('sha256', SECRET)
      .update(signedPayload)
      .digest('hex');

    // 4) Constant-time comparison
    const ok = v1 && expected.length === v1.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
    if (!ok) return res.status(400).send('invalid signature');

    const event = JSON.parse(raw.toString('utf8'));
    // Deduplicate on event.id, then respond immediately and process later
    res.status(200).send('ok');
  });

import hmac, hashlib, time, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WTHAIQ_WEBHOOK_SECRET"].encode()  # whsec_... as bytes
TOLERANCE = 300  # Seconds

@app.post("/hooks/wthaiq")
def handle():
    raw = request.get_data()               # Raw bytes — do not use request.json
    header = request.headers.get("Wthaiq-Signature", "")

    # 1) Extract t and v1
    parts = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
    t, v1 = parts.get("t"), parts.get("v1")

    # 2) Timestamp window (5 minutes)
    if not t or abs(time.time() - int(t)) > TOLERANCE:
        abort(400)

    # 3) Recompute the HMAC over "{t}.{raw_body}"
    signed_payload = f"{t}.".encode() + raw
    expected = hmac.new(SECRET, signed_payload, hashlib.sha256).hexdigest()

    # 4) Constant-time comparison
    if not v1 or not hmac.compare_digest(expected, v1):
        abort(400)

    event = request.get_json()
    # Deduplicate on event["id"], then respond immediately and process later
    return "", 200

<?php
$secret = getenv('WTHAIQ_WEBHOOK_SECRET');   // whsec_...
$tolerance = 300;                           // seconds

// Read the raw body — never use $_POST
$raw    = file_get_contents('php://input');
$header = $_SERVER['HTTP_WTHAIQ_SIGNATURE'] ?? '';

// 1) Extract t and v1
$parts = [];
foreach (explode(',', $header) as $kv) {
    [$k, $v] = array_pad(explode('=', $kv, 2), 2, '');
    $parts[$k] = $v;
}
$t  = $parts['t']  ?? '';
$v1 = $parts['v1'] ?? '';

// 2) Timestamp window (5 minutes)
if ($t === '' || abs(time() - (int)$t) > $tolerance) {
    http_response_code(400);
    exit('timestamp out of tolerance');
}

// 3) Recompute the HMAC over "{t}.{raw_body}"
$signedPayload = $t . '.' . $raw;
$expected = hash_hmac('sha256', $signedPayload, $secret);

// 4) Constant-time comparison
if ($v1 === '' || !hash_equals($expected, $v1)) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($raw, true);
// Deduplicate on $event['id'], then respond immediately and process later
http_response_code(200);
echo 'ok';

What happens on failure, and how to build a robust handler

Test your integration before launch

Build your integration with a test key sk_test_; its events carry livemode:false and nothing is charged and no message is sent to anyone. Register the webhook endpoint with the same test key via POST /v1/webhook_endpoints so that test events reach it, since endpoints added from the developer console are live. Then create a test request with your email and open the signing link yourself to receive the events signature_request.* and signer.* to your endpoint without affecting real customers.

# Create a small real request (use your own email as the recipient) to generate real events — it counts as one send from your plan allowance
curl -X POST https://wthaiq.com/api/v1/signature_requests \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Webhook test",
    "source": {"type":"template","template_id":"tpl_employment"},
    "legal_level": "ses",
    "signers": [{"name":"Developer","email":"you@example.com","method":"draw"}]
  }'

A checklist for a production integration

• Verify every request before processing it; do not trust any payload that is unsigned or outside the timestamp window.
• Use the raw body literally in the HMAC computation, before any JSON parsing.
• Make your processing idempotent by storing event.id and ignore duplicates.
• Return 2xx quickly then process the heavy work asynchronously.
• Do not assume any ordering; query the latest status through the API whenever you need certainty.
• Use a separate secret for each endpoint and store it in an environment variable, and rotate it periodically.
• Keep test events separate from live ones. Field livemode equals false in events from test keys; so do not apply any real effect to them in your system.
• Subscribe only to what you need via enabled_events to reduce noise and load.
• Monitor deliveries from the developer console and resend when necessary.
• Always use HTTPS and never expose the secret in logs or error messages.

Developer questions about Webhooks