When a payment or a verification changes state, Fintech Core delivers a webhook to
every active endpoint the business has registered. Each endpoint has its own signing
secret. Payments and KYC share one channel deliberately — one delivery log, one retry
policy, one place to look when something did not arrive.
Events
Payments
Identity verification
See Verifying customers for the full flow.
Never treat KYC_NEEDS_REVIEW as a yes. A possible sanctions match is never
cleared automatically. Wait for KYC_REVIEW_RESOLVED and read its verdict.
Payload
A POST with Content-Type: application/json. Payment events look like this:
KYC events carry the decision, never the applicant’s identity — no name, no
document number, no image. Dinari does not hold them:
Verifying the signature
Each request carries an X-Signature: sha256=<hex> header — an HMAC-SHA256 of the raw
request body using that endpoint’s secret. Always verify it before trusting the payload:
Compute the HMAC over the exact bytes received (do not re-serialize the JSON first).
Delivery & retries
- Each (endpoint, event) is delivered independently; a
2xx marks it delivered.
- Non-
2xx or network errors are retried with exponential backoff (up to 8 attempts),
then marked failed.
- Retries resend identical bytes, so the signature stays valid. Deduplicate on
payment_id + event (or application_id + event for KYC) if you process
at-least-once.
Manage endpoints (add, rotate secret, disable) in Managing businesses.