11.12 Provider webhooks

POST /api/v1/webhooks/{provider}

Purpose. Receives provider callbacks. Verifies the signature, records the event durably, and triggers provider-side verification.
Authentication. None. The provider HMAC signature is the authentication (see Section 8).
Path. provider: flutterwave, paystack, fincra, squad, termii, twilio (case-insensitive).
Body. The raw provider body (JSON; Twilio sends form-encoded data). Max 1 MiB.
Headers. The provider's signature header (see Section 8.1).

Example (Paystack, placeholder signature):

curl -s -X POST https://dffms.org/api/v1/webhooks/paystack \
  -H 'Content-Type: application/json' \
  -H 'x-paystack-signature: <hmac-sha512-hex-of-raw-body>' \
  --data-binary @paystack-event.json

Response (200):

{
  "data": { "accepted": true, "duplicate": false, "eventId": "<provider-event-id>" },
  "error": null,
  "requestId": "<request-id>"
}

Errors:

HTTP	Code	Meaning
401	`INVALID_WEBHOOK`	Signature missing or invalid; no reference; unknown or ambiguous transaction reference; invalid JSON.
404	`NOT_FOUND`	Provider name not supported.
413	`PAYLOAD_TOO_LARGE`	Over 1 MiB.
500	`INTERNAL_ERROR`	Unhandled error.
503	`PROVIDER_DISABLED`	Provider's webhook secret not configured.
503	`FEATURE_UNAVAILABLE`	SMS status callbacks (`termii`, `twilio`), after successful verification.

Side effects (payment providers): inbox row, outbox payment.webhook.received, background processing (see Section 8.2). Duplicates return 200 with duplicate: true and create nothing.

POST /api/v1/webhooks/{provider}​

POST /api/v1/webhooks/{provider}