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:
| Event | When it fires |
|---|---|
charge.initialize | Payment created via /api/v1/transactions/initialize or /initialize-intl |
charge.processing | Gateway accepted the charge and it is in flight |
charge.completed | Final successful charge (data.status typically 00) |
charge.failed | Final 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);
81Configure 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.
| Field | Prefix | Use when webhook arrives |
|---|---|---|
live_webhook_secret / test_webhook_secret | whsec_* | Verify X-Spout-Signature (HMAC-SHA256) |
live_encryption_key / test_encryption_key | enc_* | 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
- Read the raw body (bytes before JSON parse)
- Verify signature with
whsec_* - If
encryptedis present, decrypt withenc_* - Otherwise use clear
data - Return
200 OK, then process asynchronously
Delivery headers
| Header | Purpose |
|---|---|
X-Spout-Signature | t=<unix>,v1=<hmac-sha256-hex> over the string `${t}.${rawBody}` |
X-Spout-Event | Event type string |
X-Spout-Delivery-Id | Same 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 };
38Decrypt 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;
29Test 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, or99.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
- Add live and test webhook URLs in settings
- Store
whsec_*andenc_*from API key creation securely - Verify
X-Spout-Signatureon every request - Return
200 OKbefore long-running work - Subscribe only to the events you need via
subscribed_events - Enable
encryptPayloadonly after your decrypt path is tested - Localhost URLs cannot receive live deliveries