Webhook

Hipay uses webhook to notify your application any time an event happens on your account. Set up webhook for events that Hipay doesn't already notify you of, like when a disbursement has been completed, a Virtual Account has been created and paid, or your invoice has expired.

Setup

You need to provide an endpoint in your system to receive webhook from us. The webhook notification will be sent over POST request to your webhook URL that you have set. Setup your webhook URL in webhook settings. You can use a tool like ngrok to make your endpoint available for receiving webhook during testing.

Delivery Attempts and Retries

Understand how to view delivery attempts and retry logic when webhook events aren't acknowledged

View events

When viewing information about a specific event through the Dashboard's Webhook tab, you can check how many times Hipay attempted to send an event to the endpoint. This shows the latest response from your endpoint, a list of all attempted webhooks, and the respective HTTP status codes Hipay received.

Retry logic

Hipay attempts to deliver your webhook six times with exponential backoff between each interval and will stop retrying until we have received response from your server or there is still no response yet

Retry Number	Interval (relative to last retry)	Interval (relative to original attempt)
1	15m	15m
2	45m	1h
3	2h	3h
4	3h	6h
5	6h	12h
6	12h	24h

Receive webhook statistics via email

You can also receive summary of your webhook statistics (number of success and failed webhook) via email every 6 hours. You can enable this feature in Email Recipient settings

Event Handling

Handling webhook events correctly is crucial to making sure your integration's business logic works as expected

Acknowledge events immediately

If your webhook script performs complex logic, or makes network calls, it's possible that the script would time out before Hipay sees its complete execution. Ideally, your webhook handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that event.

Handle duplicate events

Webhook endpoints might occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by making your event processing idempotent. One way of doing this is logging the events you've processed, and then not processing already-logged events. We provide webhook-id as a unique identifier in the header parameter of every webhook to help you to implement idempotency. Learn about idempotency.

Order of events

Hipay does not guarantee delivery of events in the order in which they are generated. Your endpoint should not expect delivery of these events in this order and should handle this accordingly. You can also use the API to fetch any missing objects.

Security

Keeping your endpoints secure is critical to protecting your customers' information. Hipay provides several ways for you to verify events are coming from Hipay in a secure manner.

Receive events with an HTTPS server

If you use an HTTPS URL for your webhook endpoint, Hipay will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.

Verify events are sent from Hipay

Hipay can optionally sign the webhook events it sends to your endpoints. We do so by including a token in each event's x-callback-token header. This allows you to verify that the events were sent by Hipay, not by a third party.

Header Parameter	Description
x-callback-token	string Your Hipay unique webhook token to verify the origin of the webhook

Before you can verify tokens, you need to retrieve your webhook token from Dashboard's Webhook settings. Each secret is unique to each environments.