Webhooks

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:

  • Transfers .
  • Provisioning Merchant accounts.
  • Events for newly created Disputes .

Creating Webhooks

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.

Authenticating Webhooks

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.

Delivery Attempts and Retries

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.

Frequently Asked Questions

Will I receive a request for each event, or will I receive them in batches?

  • You will receive a request for each individual event. Webhooks created at the Application level receive any state change under an Application . These changes include a change in state for a Transfer , Merchant account provisioning, and Disputes .

Is there a specific time when events get sent?

  • 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.

Is there a list of all the webhook events?

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.

Do need to whitelist a specific IP address?

  • We submit requests from multiple IP addresses.

How do I verify the event is from Finix?

  • 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.

How many times will you try to send a webhook that fails?

  • Finix makes five attempts to retry sending a Webhook event; the event won't get sent again after five attempts.