Skip to main content

Webhooks

Info

Webhooks allow external systems to push event notifications to SmartPay. These endpoints receive payment confirmations, message events, and other real-time updates.

Features​

VULT Integration

Receive cash-in notifications from VULT processor

WhatsApp Messages

Process WhatsApp messages via Agent-TS

HMAC Verification

Secure webhook payloads with signature verification

Real-time Processing

Instant event handling and response

Endpoints​

VULT Webhook

POST /webhooks/vult/cashin

Receive VULT cash-in notifications

WhatsApp Webhook

POST /api/v1/external/whatsapp

Process WhatsApp messages

Webhook Security​

Warning

All webhooks should verify the signature before processing:

  1. Extract signature from header (X-Webhook-Signature or equivalent)
  2. Compute HMAC-SHA256 of the raw request body
  3. Compare signatures using timing-safe comparison
  4. Reject requests with invalid or missing signatures

Webhook Flow​

Event Occurs

External system (VULT, WhatsApp) generates an event

Webhook Sent

System sends HTTP POST to configured endpoint with signed payload

Verify Signature

SmartPay verifies HMAC signature before processing

Process Event

Event is processed (e.g., credit wallet, respond to message)

Acknowledge

Return success response to confirm receipt