Managing Webhooks

Use Webhooks to subscribe to automated notifications (i.e. events) from Finix's API.

When an events is triggered, a HTTP POST payload is sent to the URL that's configured in the webhook. Instead of manually pulling information from the API, webhooks push notifications to the configured URL.

Webhooks are useful for updating asynchronous state changes. This includes:

  • Transfers .
  • Merchant account provisioning.
  • Events for newly created Disputes .

Creating Webhooks

You can create webhooks using your Finix Dashboard or Finix's API.

To create a webhook on the Finix Dashboard:

  1. Navigate to the PEOPLE header. Click Applications .
  2. Select the Application . Click the WEBHOOKS tab on the top navigation bar.
  3. Click Create Webhook and enter your webhook URL.
  4. Click Submit .

For details on how to create a webhook using Finix's API, see Create a Webhook.

Frequently asked questions

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

  • You will receive a request for each individual event. For application Webhooks you’ll receive them for any state change that occurs with an Application. Such as a change in state for a Transfer , Merchant account provisioning, and Disputes.

Is there a specific time at which events will be sent?

  • Whenever a state change occurs in the database the event will be fired off, thus making them as real-time as possible.

Is there a way to tell Finix that the event was successfully received? What type of response should we send?

  • Any type of 200 HTTP code will suffice.

If the event wasn’t received, is it going to be sent again? What type of response/exception should I send?

  • Yes, if no response from the end-point is received by the Webhook it automatically will be replayed.

Is Finix sending any confidential information? I’d like to know if using a public service, like, for testing the Webhooks is an option.**

  • Yes, you can use to test Webhooks . We won’t ever send sensitive credit card data, but will return DOBs and addresses. You can review the sample payloads .

Is there a list of all the event types and their payload?**

I’ll need a way to make sure that the same event is not processed twice, is it possible to include a unique ID in each request?

  • We currently do not have this capability. It is on the roadmap, but unfortunately we don’t have a definitive timeframe.

I’ll need a way to consolidate our transactions with the information received from the event. Is there a processor transaction ID that will be sent with each event?

Do I only need to whitelist a single IP?

  • We submit the requests from multiple IP addresses.

How do I validate that Finix is the right caller?

  • We can provide you a list of the IP addresses where you can expect to receive the events.

When I update the URL of a Webhook through the API is there a delay before the new URL starts sending events? Do we need a grace period for the previous URL?

  • There shouldn’t be any delays, but you can actually have multiple webhooks enabled at the same time to prevent any issues for migrating over to a new URL.

How many retries and at which frequency will you send Webhooks?

  • There are five attempts to retry sending a Webhook event. The event won't be sent again after the five attempts.