Octopus POS SDK Integration Guide Addendum

11. Webhook Configuration

Configure webhooks to send real-time transaction notifications to aggregators[cite: 225]. [cite_start]The Macrotech webhook system delivers HTTP POST requests to your registered endpoint whenever a transaction event occurs[cite: 225].

11.1 Event Types

The following events are emitted asynchronously by the gateway server engine:

11.2 Request Headers

Every incoming HTTP POST mutation payload features standard structural transaction metadata wrapped inside the connection request headers:

11.3 Request Payload

The webhook payload is a JSON object structure containing comprehensive merchant breakdown parameters and ISO network state codes[cite: 231]:

{
  "eventType": "TRANSACTION_APPROVED",
  "transactionId": 12345,
  "stan": "123456",
  "rrn": "123456789012",
  "merchantId": 100,
  "merchantName": "Adebayo Supermarket",
  "terminalId": 200,
  "terminalTid": "T12345678",
  "amount": "25000.00",
  "currency": "NGN",
  "status": "APPROVED",
  "responseCode": "00",
  "responseMessage": "Transaction Approved",
  "authCode": "ABC123",
  "timestamp": "2024-01-15T14:30:00"
}

Data Field Dictionary Blueprint

11.4 Response Format

Your webhook server must respond with a 2xx HTTP status code within 10 seconds[cite: 253]. [cite_start]A response body is optional but recommended for debugging and audit purposes[cite: 254]:

{
  "status": "received",
  "message": "Webhook processed successfully",
  "timestamp": "2024-01-15T14:30:01"
}

11.5 Signature Verification

When a webhook secret is configured on the Macrotech dashboard, each request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the JSON payload encoded in Base64[cite: 263]. [cite_start]Always verify this signature before processing the event to confirm the request originated from Macrotech[cite: 264].

Node.js Implementation Example

const crypto = require('crypto');

function verifySignature (payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('base64');
    
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
app.post('/webhook/endpoint', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifySignature(req.body, signature, 'your-secret-key');
  
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process the webhook
  console.log('Received event:', req.body.eventType);
  res.status(200).json({ status: 'received' });
});

11.6 cURL Simulation Node

Execute this diagnostic payload from your command terminal to test your endpoint's network intake pipeline manually:

curl -X POST https://your-server.com/webhook/endpoint \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: <signature>" \
  -H "X-Event-Type: TRANSACTION_APPROVED" \
  -H "X-Transaction-ID: 12345" \
  -d '{
    "eventType": "TRANSACTION_APPROVED",
    "transactionId": 12345,
    "stan": "123456",
    "amount": "25000.00",
    "status": "APPROVED",
    "responseCode": "00",
    "timestamp": "2024-01-15T14:30:00"
  }'

11.7 Important Operational Notes

[cite_start]
• Webhooks are sent asynchronously and will retry up to the configured number of attempts on failure[cite: 310].
[cite_start]
• Your endpoint must respond within the configured timeout period to be considered successful[cite: 311].
[cite_start]
• Always verify the X-Webhook-Signature header to confirm the request is from Macrotech[cite: 312].
[cite_start]
• Design your handler to be idempotent — duplicate webhooks may be delivered during network retry sequences[cite: 313].
[cite_start]
• Event ordering is not guaranteed[cite: 313]. [cite_start]Use the timestamp field for chronological ordering[cite: 314].