Webhooks

Receive signed HTTP notifications when payments, refunds, invoices, subscriptions and other resources change state.

Configuration

In the developer console, open your API app and add webhook endpoints: an HTTPS URL, the events it receives and its own signing secret (shown once). An app can have several endpoints (for example one per system); the app's webhook URL is its default endpoint. Endpoints can also be managed with /v1/developer/apps/{id}/webhook-endpoints.

New apps subscribe to payment.capture.completed and payment.capture.declined by default. Subscribe to * to receive every event.

The event object

Every webhook body is the same event envelope, whether it is a live delivery, a retry, a simulated event or a dashboard “send test”. The type is a canonical registry id (e.g. payment.capture.completed), and the resource lives under data.object. Test events (livemode: false, from test keys, the simulator and “send test”) go only to test apps; live events only to live apps.

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "object": "event",
  "type": "payment.capture.completed",
  "api_version": "2026-10-29",
  "livemode": false,
  "created": 1717406400,
  "data": {
    "object": {
      "id": "txn_01HQXYZ",
      "object": "transaction",
      "amount": "25.0000",
      "currency": "USD",
      "status": "completed",
      "merchant_transaction_id": "ORD-1001",
      "metadata": { "order_id": "ORD-1001" },
      "livemode": false
    }
  }
}

Signature verification

Each delivery carries a Watenga-Signature header. It contains a Unix timestamp and an HMAC-SHA256 signature, comma-separated:

Watenga-Signature: t=1717406400,v1=5257a869e7ec3ead4f1b0f8b5b1f8b6f9f0c2e1d3a4b5c6d7e8f9a0b1c2d3e4f

# While a signing secret rotates, one v1 per secret:
Watenga-Signature: t=1717406400,v1=<signed with the new secret>,v1=<signed with the old secret>

The signed payload is the timestamp and the raw request body joined by a dot: `${t}.${rawBody}`. Recompute the HMAC-SHA256 with your endpoint's signing secret and accept the delivery when it equals any v1 in the header (constant-time comparison).

Node.js

const crypto = require('crypto');

// Watenga-Signature: t=<unix-seconds>,v1=<hmac-sha256-hex>[,v1=<hmac>] (one v1 per secret while rotating)
function verify(rawBody, header, secret, toleranceSeconds = 300) {
  let timestamp = NaN;
  const signatures = [];
  for (const part of String(header || '').split(',')) {
    const [key, value] = part.split('=').map((s) => s && s.trim());
    if (key === 't') timestamp = Number(value);
    if (key === 'v1' && value) signatures.push(value);
  }
  if (!Number.isFinite(timestamp) || signatures.length === 0) return false;
  // Reject replays: more than 5 minutes either way.
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = Buffer.from(crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`, 'utf8').digest('hex'));
  return signatures.some((sig) => {
    const given = Buffer.from(sig);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

if (!verify(req.rawBody, req.headers['watenga-signature'], process.env.WATENGA_WEBHOOK_SECRET)) {
  return res.sendStatus(400);
}
const event = JSON.parse(req.rawBody); // { id, object: 'event', type, api_version, livemode, created, data: { object } }

PHP

$header = $_SERVER['HTTP_WATENGA_SIGNATURE'] ?? '';
$timestamp = null;
$signatures = [];
foreach (explode(',', $header) as $segment) {
    [$k, $v] = array_pad(explode('=', trim($segment), 2), 2, '');
    if ($k === 't' && ctype_digit($v)) { $timestamp = (int) $v; }
    if ($k === 'v1' && $v !== '') { $signatures[] = $v; } // one v1 per secret while rotating
}

// Reject replays: more than 5 minutes either way.
if ($timestamp === null || !$signatures || abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$rawBody = file_get_contents('php://input');
$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, getenv('WATENGA_WEBHOOK_SECRET'));
$valid = false;
foreach ($signatures as $signature) {
    if (hash_equals($expected, $signature)) { $valid = true; }
}
if (!$valid) {
    http_response_code(400);
    exit;
}

$event = json_decode($rawBody, true); // $event['type'], $event['data']['object']

The SDKs verify for you (and accept two secrets while you rotate): Node.js, Python, PHP, Go and Dart.

Rotating a signing secret

Rotate an endpoint's secret in the developer console (two-step verification) and choose how long the old secret keeps signing: up to 7 days, 24 hours by default, or end it at once if it leaked. During the overlap every delivery carries a v1 signature for each secret, so your endpoint verifies with either while you deploy the new one; then remove the old secret from your configuration.

Testing on your machine

watenga listen --forward-to http://localhost:3000/webhooks forwards your test app's events to your machine, signed with a session secret it prints; watenga trigger payment.capture.completed sends one (CLI). No tunnel needed.

Retry policy

Answer with a 2xx status within 15 seconds; do the work after answering. Any other status, or no answer, is retried for about three days: after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours, 10 hours, 20 hours and 24 hours (10 tries in all). The same event can arrive more than once: use its id to handle it once.

An endpoint that keeps failing is reported in the dashboard; one failing for three days is switched off (switch it back on in the console). Every delivery is in the app's delivery log, where you can send one again, or every failed one of an endpoint in a time window.

Events emitted today

These events are currently delivered by Watenga. The full registry — including events reserved for upcoming features — is available from GET /v1/meta/webhook-events and the catalogue below.

Full event catalogue

Generated from the canonical webhook event registry in @watenga/shared (mirrored to content/webhook-events.generated.md). “Live” events are delivered today; others are reserved for upcoming features.