Skip to main content
Build a webhook endpoint to receive and process events from Fintoc. A webhook endpoint works like any other application endpoint, with additional delivery and retry considerations. Review Webhook best practices before implementing your endpoint.

Key considerations

When an event occurs, Fintoc sends a POST request with a JSON body to every registered webhook endpoint. Parse the JSON body to access the event details. Your webhook endpoint must parse the POST request and return a status code in the 2xx range.

Save the received event

Every webhook event sent by Fintoc has a unique id. Save each event id in your application’s database. Use the saved id to detect duplicate deliveries and process each event only once.

Return a 2xx status code before the timeout

To confirm receipt of an event, respond with a 2xx HTTP status code. Fintoc treats any other status code as a failed attempt. Respond with a 2xx status code before Fintoc’s delivery timeout. Run logic that does not need to complete before acknowledgment asynchronously so the handler returns before the timeout.

Handle retries and failed deliveries

Fintoc treats a delivery as a failed attempt if your endpoint responds with any status code outside the 2xx range or if the request times out. When a delivery fails, Fintoc automatically retries it using exponential backoff, starting 3 seconds after the failed attempt. Fintoc makes up to 17 retry attempts for each event. If every attempt fails, Fintoc stops retrying that event. The following limitations apply:
  • Fintoc does not disable the webhook endpoint automatically or notify you when it stops retrying an event.
  • Fintoc does not support manual replay or a dead-letter mechanism to resend a failed event.
Fintoc can deliver the same event more than once, so your endpoint must be idempotent. To handle duplicate events, see Avoid event duplication.

Test the webhook

Fintoc sends webhook events only when the underlying action occurs. A handler bug can therefore go unnoticed until the endpoint receives production traffic. Test your endpoint when you create it, register it, or change how it receives events. For the step-by-step test procedure, including how to expose your local endpoint and send a test event, see Test your webhook endpoint.

Sample code

Webhook handler (Python)
Webhook handler (Node.js)