Use webhooks to subscribe to automated notifications (also known as events) from Finix's API.
When an event is triggered, an HTTP POST payload gets sent to the endpoint URL configured in the webhook. So instead of manually pulling information from Finix's API, webhooks push notifications to the endpoint URL.
With webhooks, you can keep up with asynchronous state changes. These changes include:
Events for newly created
You can create webhooks using Finix's API.
When a webhook gets created, Finix sends an empty test event to the endpoint URL configured in the webhook.
The endpoint URL you use needs to respond to this empty event with a 2xx HTTP code to let Finix know you received the event and the endpoint URL is valid. If the endpoint URL is validated, a successful response will return, and the webhook will be enabled.
For details on how to create a webhook using Finix's API, see Create a Webhook.
When creating a webhook, specify the Authentication Type Finix should use when sending events to the endpoint URL.
Including an Authentication type adds an authentication header to every event sent to the configured endpoint URL. You can refer to the event's authentication header to confirm that Finix created the event.
You can confirm the webhooks originated from Finix by:
- Basic : Verify the response returns BASIC as the authentication header and the Username and Password headers match what's configured in the webhook.
- Bearer Token (Oauth 2.0) : Verify the response returns BEARER as the authentication header, and the Bearer token matches what's configured in the webhook.
Finix attempts to send individual webhook events five times. However, the event won't get sent again after five attempts.
After an extended period, if an endpoint URL hasn't accepted any events or responded with a successful 2xx HTTP status code Finix will disable the webhook and proactively reach out to you about how the webhook is configured (Sandbox only).
Verifying webhooks work in your Sandbox environment helps you confirm your webhook implementation is working before moving it to your live environment. Please note that Finix will not disable webhooks configured in live environments.
You will receive a request for each individual event. Webhooks created at the
Applicationlevel receive any state change under an
Application. These changes include a change in state for a
Merchantaccount provisioning, and
- An event gets sent any time a state change occurs in our database; this helps make webhook events as real-time as possible.
What type of response should we send? Is there a way to notify Finix that an event got received successfully?
- Any 2xx HTTP code will let Finix know the event got successfully received.
If we don't receive the event, will it be sent again? What type of response/exception should I send?
- Yes, if no response gets received from the endpoint, the webhook automatically replays and resends the event.
Is Finix sending any confidential information? I’d like to know if using a public service, like https://pipedream.com, is an option to test webhooks.
- Yes, you can use https://pipedream.com to test webhooks. We won’t ever send sensitive credit card data but will return DOBs and addresses. You can review our list of sample webhook events .
- Yes, here’s a list of every webhook event Finix sends.
Is it possible to include a unique ID in each request? I want to make sure the same event isn't processed twice.
- Currently, we don't offer the option to include unique IDs with webhook events. We don't have a concrete timeline, but we plan on releasing this capability in the future.
Is there a processor transaction ID that gets sent with each event? I need a way to consolidate our transactions using the information received from the event.
- Use the resource ID’s in each response to consolidate events. For example:
- Transfer (e.g. debit, refund, credit)
- We submit requests from multiple IP addresses.
- Authenticate your webhooks so events include an authorization header. Refer to the authorization header to confirm that events are from Finix.
If I change the endpoint URL of a webhook, will there be a delay before events get sent to the new URL? Can we deactivate the old endpoint URL immediately, or do we need to wait?
- There shouldn’t be any delay. To prevent migration issues, you can enable multiple at the same time. You can immediately deactivate the old endpoint URL and disable the old webhook.
- Finix makes five attempts to retry sending a Webhook event; the event won't get sent again after five attempts.