spout

Webhooks

Webhooks let SpoutPay push real-time payment updates to your server so you do not need to poll. Each delivery is HMAC-SHA256 signed, and you can optionally receive an AES-256-GCM encrypted payload.

Lifecycle events

Subscribe to the events you care about via webhook settings (subscribed_events). Defaults include all four:

EventWhen it fires
charge.initializePayment created via /api/v1/transactions/initialize or /initialize-intl
charge.processingGateway accepted the charge and it is in flight
charge.completedFinal successful charge (data.status typically 00)
charge.failedFinal failed charge (declined, 99, etc.). Suppressed when enableForFailed is false

Email receipts and dashboard alerts are covered under Notifications.

Create a webhook URL

Expose a public POST endpoint that (1) reads the raw body, (2) verifies X-Spout-Signature with HMAC-SHA256, (3) optionally decrypts AES-256-GCM, then (4) returns 200 OK quickly.

Signing string: `${t}.${rawBody}` · Header: t=<unix>,v1=<hex> · Secret: whsec_* · Encrypt key (optional): enc_*

1const express = require("express");
2const crypto = require("crypto");
3
4const app = express();
5const WEBHOOK_SECRET = process.env.SPOUT_WEBHOOK_SECRET; // whsec_live_... or whsec_test_...
6const ENCRYPTION_KEY = process.env.SPOUT_ENCRYPTION_KEY; // enc_live_... or enc_test_...
7
8function verifySignature(rawBody, signatureHeader, secret, toleranceSec = 300) {
9  if (!signatureHeader || !secret) return false;
10  const parts = Object.fromEntries(
11    signatureHeader.split(",").map((p) => {
12      const [k, ...rest] = p.trim().split("=");
13      return [k, rest.join("=")];
14    })
15  );
16  const t = Number(parts.t);
17  const v1 = parts.v1;
18  if (!t || !v1) return false;
19  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
20
21  const expected = crypto
22    .createHmac("sha256", secret)
23    .update(`${t}.${rawBody}`)
24    .digest("hex");
25
26  try {
27    return crypto.timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
28  } catch {
29    return false;
30  }
31}
32
33function decryptEncrypted(encrypted, encryptionKey) {
34  const key = crypto.createHash("sha256").update(encryptionKey).digest();
35  const decipher = crypto.createDecipheriv(
36    "aes-256-gcm",
37    key,
38    Buffer.from(encrypted.iv, "base64")
39  );
40  decipher.setAuthTag(Buffer.from(encrypted.tag, "base64"));
41  const pt = Buffer.concat([
42    decipher.update(Buffer.from(encrypted.ciphertext, "base64")),
43    decipher.final(),
44  ]);
45  return JSON.parse(pt.toString("utf8"));
46}
47
48// IMPORTANT: use raw body — do not use express.json() before this route
49app.post(
50  "/webhooks/spout",
51  express.raw({ type: "application/json" }),
52  (req, res) => {
53    const rawBody = Buffer.isBuffer(req.body)
54      ? req.body.toString("utf8")
55      : String(req.body);
56    const signature = req.headers["x-spout-signature"];
57
58    if (!verifySignature(rawBody, signature, WEBHOOK_SECRET)) {
59      return res.status(401).send("invalid signature");
60    }
61
62    const envelope = JSON.parse(rawBody);
63    const event = envelope.encrypted
64      ? decryptEncrypted(envelope.encrypted, ENCRYPTION_KEY)
65      : envelope;
66
67    res.status(200).send("ok");
68
69    // process asynchronously after ack
70    switch (event.type) {
71      case "charge.completed":
72        // fulfill order using event.data.spout_tx_ref
73        break;
74      case "charge.failed":
75        break;
76      default:
77        break;
78    }
79  }
80);
81

Configure the URL in the SpoutPay dashboard or via POST /api/v1/settings/webhook (JWT auth). Required on create: live_url, resciveInJson, enableRetries, enableForFailed, enableSendFromDashboard. Optional: test_url, encryptPayload, subscribed_events. Update with PATCH /api/v1/settings/webhook.

Create webhook body

1{
2  "live_url": "https://merchant.example.com/webhooks/spout",
3  "test_url": "https://merchant.example.com/webhooks/spout-test",
4  "resciveInJson": true,
5  "enableRetries": true,
6  "enableForFailed": true,
7  "enableSendFromDashboard": false,
8  "encryptPayload": false,
9  "subscribed_events": [
10    "charge.initialize",
11    "charge.processing",
12    "charge.completed",
13    "charge.failed"
14  ]
15}

Keys from API key generation

When you create API keys via POST /api/v1/settings/apikey, Spout also generates dedicated webhook credentials. Save them from the create response — they are what you use when a webhook is received.

FieldPrefixUse when webhook arrives
live_webhook_secret / test_webhook_secretwhsec_*Verify X-Spout-Signature (HMAC-SHA256)
live_encryption_key / test_encryption_keyenc_*Decrypt encrypted AES-256-GCM payload when encryptPayload is enabled

These are not your live_secret_key / test_secret_key (those authenticate API requests). Suggested env vars: SPOUT_WEBHOOK_SECRET and SPOUT_ENCRYPTION_KEY.

Create API key response

1{
2  "status": 200,
3  "data": {
4    "message": "Api Key successfully set. Store webhook secrets and encryption keys securely — they are used to verify and decrypt webhook deliveries.",
5    "live_secret_key": "SPT_LIVE_SK...",
6    "live_pub_key": "SPT_LIVE_PK...",
7    "test_secret_key": "SPT_TEST_SK...",
8    "test_pub_key": "SPT_TEST_PK...",
9    "live_webhook_secret": "whsec_live_...",
10    "test_webhook_secret": "whsec_test_...",
11    "live_encryption_key": "enc_live_...",
12    "test_encryption_key": "enc_test_..."
13  }
14}

Missing keys are backfilled on GET /api/v1/settings/apikey. Rotate both pairs with POST /api/v1/settings/webhook-secrets/rotate.

Receive flow

  1. Read the raw body (bytes before JSON parse)
  2. Verify signature with whsec_*
  3. If encrypted is present, decrypt with enc_*
  4. Otherwise use clear data
  5. Return 200 OK, then process asynchronously

Delivery headers

HeaderPurpose
X-Spout-Signaturet=<unix>,v1=<hmac-sha256-hex> over the string `${t}.${rawBody}`
X-Spout-EventEvent type string
X-Spout-Delivery-IdSame as the event id

Event payload

Clear JSON

1{
2  "id": "evt_01abc...",
3  "type": "charge.completed",
4  "created_at": "2026-11-18T17:00:00.000Z",
5  "livemode": true,
6  "data": {
7    "spout_tx_ref": "SP-a1b2c3d4",
8    "merchant_tx_ref": "order_1001",
9    "amount": 1000,
10    "currency": "NGN",
11    "status": "00",
12    "gateway_response": "Approved",
13    "customer_name": "Jane Doe",
14    "email_address": "jane@example.com",
15    "phone_number": "08012345678",
16    "request_type": "CARD",
17    "description": "Order 1001",
18    "transaction_date": "2026-11-18T17:00:00.000Z",
19    "charge": 15
20  }
21}

When config.encryptPayload is true, clear data is omitted and replaced by an encrypted AES-256-GCM envelope. Always verify the HMAC on the raw body first.

Encrypted envelope

1{
2  "id": "evt_01abc...",
3  "type": "charge.completed",
4  "created_at": "2026-11-18T17:00:00.000Z",
5  "livemode": true,
6  "encrypted": {
7    "alg": "aes-256-gcm",
8    "iv": "<base64>",
9    "tag": "<base64>",
10    "ciphertext": "<base64>"
11  }
12}

Verify event origin (HMAC)

Your webhook URL is public. Verify that events come from SpoutPay before you update orders or wallets.

Signature validation (required)

Compute HMAC-SHA256 of `${t}.${rawBody}` with your whsec_* secret and compare it to v1 using a constant-time check. Reject stale timestamps (default tolerance 5 minutes).

1const crypto = require("crypto");
2
3/**
4 * X-Spout-Signature: t=<unix>,v1=<hmac-sha256-hex>
5 * Signed string: `${t}.${rawBody}`  (rawBody = exact request bytes as utf8)
6 */
7function verifySignature(rawBody, signatureHeader, webhookSecret, toleranceSec = 300) {
8  if (!signatureHeader || !webhookSecret) return false;
9
10  const parts = Object.fromEntries(
11    signatureHeader.split(",").map((p) => {
12      const [k, ...rest] = p.trim().split("=");
13      return [k, rest.join("=")];
14    })
15  );
16
17  const t = Number(parts.t);
18  const v1 = parts.v1;
19  if (!t || !v1) return false;
20  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
21
22  const expected = crypto
23    .createHmac("sha256", webhookSecret)
24    .update(`${t}.${rawBody}`)
25    .digest("hex");
26
27  try {
28    return crypto.timingSafeEqual(
29      Buffer.from(v1, "hex"),
30      Buffer.from(expected, "hex")
31    );
32  } catch {
33    return false;
34  }
35}
36
37module.exports = { verifySignature };
38

Decrypt with your encryption key (optional)

When encryptPayload is true, Spout encrypts with your live_encryption_key / test_encryption_key. AES key = SHA-256(enc_*) (32 bytes). Fields iv, tag, ciphertext are base64. Never use the API secret key or HMAC secret for decrypt.

1const crypto = require("crypto");
2
3/**
4 * Decrypt AES-256-GCM envelope from Spout when encryptPayload is enabled.
5 * Key material: live_encryption_key / test_encryption_key (enc_*).
6 * AES key = SHA-256(encryptionKey) → 32 bytes.
7 * Envelope fields: iv, tag, ciphertext (all base64).
8 */
9function decryptEncrypted(encrypted, encryptionKey) {
10  const key = crypto.createHash("sha256").update(encryptionKey).digest();
11  const decipher = crypto.createDecipheriv(
12    "aes-256-gcm",
13    key,
14    Buffer.from(encrypted.iv, "base64")
15  );
16  decipher.setAuthTag(Buffer.from(encrypted.tag, "base64"));
17  const pt = Buffer.concat([
18    decipher.update(Buffer.from(encrypted.ciphertext, "base64")),
19    decipher.final(),
20  ]);
21  return JSON.parse(pt.toString("utf8"));
22}
23
24// After HMAC verify:
25const envelope = JSON.parse(rawBody);
26const event = envelope.encrypted
27  ? decryptEncrypted(envelope.encrypted, process.env.SPOUT_ENCRYPTION_KEY)
28  : envelope;
29

Test mode (no live processors)

Authenticate initialize with your test_secret_key. The payment is saved with mode: "test". Checkout charge calls then simulate processing and completion — UPSL, EPG, and PayAttitude are never contacted.

  • Amount 99, 999, or 99.99 → simulated decline (charge.failed)
  • Card PAN ending in 0002 → simulated decline
  • Any other amount/PAN → simulated approval (charge.completed)

Full PAN / expiry / CVV tables and QA scenarios: Test Cards. Flow overview: Test Transactions. Webhooks for test payments use your testwebhook_url, test_webhook_secret, and test_encryption_key.

Go-live checklist

  1. Add live and test webhook URLs in settings
  2. Store whsec_* and enc_* from API key creation securely
  3. Verify X-Spout-Signature on every request
  4. Return 200 OK before long-running work
  5. Subscribe only to the events you need via subscribed_events
  6. Enable encryptPayload only after your decrypt path is tested
  7. Localhost URLs cannot receive live deliveries