Foinse

Know when a payment happens.

Webhooks send a signed notification to your app when a payment settles, a dispute changes, or a quota key reaches its limit. They deliver the news; receipts and the ledger remain the official record.

How to use them

  1. Register your endpoint. Give Foinse a URL you control for event notifications.
  2. Verify every signature. Use the signing secret to confirm the notification came from Foinse before acting on it.
  3. Check the receipt. Use the referenced receipt to confirm the payment, fee, and settlement status.
Delivery and verification details

Events

Events are emitted for settlement activity: a settlement completing, a dispute opening or resolving, and key events such as a quota key reaching its allowance. Each event payload carries the grade of the underlying line, so fixture events from the sandbox are labeled fixture.

Signing

Payloads are signed. Verify the signature on every delivery before processing, using the signing secret shown when the endpoint is registered. A delivery that fails signature verification should be discarded. The signature is what ties a payload to Foinse; the payload body alone is not proof of origin.

Delivery and retries

Your endpoint must acknowledge receipt promptly. Deliveries that are not acknowledged are retried with backoff over a bounded period, then stopped. Reconciliation after a gap should be done against the ledger via the API, not by assuming every webhook arrived exactly once. Order is not guaranteed; use the receipt and timestamps in the payload to order events yourself.

Reconciliation

For every settlement event, the payload references the receipt. Verify it the same way as any receipt: conservation holds, toll matches the posted rate, grade is as labeled. See receipt verify.