Webhooks

What Are Webhooks?

A webhook is a HTTP request sent from a source system to subscriber destination systems when an event occurs in the source system. In other words, webhooks are a one-way push notification to a remote system when something happens. Webhooks are useful in that a remote system can be notified when a trigger event occurs.

This is similar to when you put your name on a waitlist and you get notified via SMS when your table is ready. By placing your name on the waitlist, you are subscribing to the event. The table becoming available is the triggering event and the SMS text sent to your phone letting you know the table was ready is the notification.

What Webhooks Does Finexio Provide?

Currently Finexio provides a “payment.change” webhook. This webhook fires whenever the system receives a new payment or when there is a new payment event acknowledged by the system that is newer than when the last webhook was sent.

Every hour, the Finexio system looks for new payments and new payment events that will trigger a webhook. If new payments are found or if new payment events (updates) are found for existing payments, subscribed systems to the payment.change event will receive one webhook notification per payment.

Webhooks are payment based, so each new payment will trigger a single webhook and new payment events (updates) for an existing payment will also trigger a single webhook for that payment. A subscriber will receive one webhook per payment per hour on any new events that occur.

Even if a payment had multiple new events on a payment, one single webhook will trigger, on the hourly run of the webhook process. The subsequent lookup of the payment by the remote system would contain all the events for that payment.

How Are Webhooks Used?

Webhooks are an optional feature that can be used to provide more granular updates when used in conjunction with polling. Polling is the process by which a remote system asks the source system for the status of something on a regular interval. Depending on the number of updates needed this can be a very expensive and time-consuming process. Depending on the time between updates, updates can occur far apart.

Utilizing webhooks in addition to polling can help provide more granular updates since remote systems can request updates based on webhook notifications to payments that have been updated in between polling periods.

Finexio does not recommend using webhooks alone. Polling is the required technique to synchronize payments on a regular basis, utilizing the optional webhook subscription to get additional updates in between polling intervals.

Payment Status Update Workflows

Are Webhooks Required?

Webhooks are an optional feature to get more frequent updates. Use of webhooks is not required and has no effect on the processing of payments. Remote systems will still receive updates during the polling period when in flight payments status are retrieved.

Subscribe to an Event

Users of Finexio’s API can create a webhooks subscription by calling the [Create Webhook Subscription API] (https://finexio.readme.io/reference/createsubscriber). Once subscribed, any subsequent new payment or new payment change event will trigger a webhook. Updates to the webhook subscription, for example changes in the URL for credentials, can be done via the Update Webhook Subscription API.

Please note: When specifying the webhook event name and callback UL, the end user needs to create a username and password. The username and password are used to verify the authenticity of an event call back. Do not use your API user credentials when creating a subscription.

See the request authentication below for more details.

Webhook Subscription Sample Request and Response

Here is an example of a create subscription request:

{
    "event": "payment.changed",
    "url": "https://testfinexioswebhook.com",
    "content_type": "application/json",
    "username": "EnterUsernameHere",
    "password": "EnterPasswordHere"
}

Here is an example of a create subscription response:

{
    "id": "6c88d1f3-fddd-4a87-b49b-5c4371b61e14",
    "event": "payment.changed",
    "url": "https://testfinexioswebhook.com",
    "content_type": "application/json",
    "user": "qatestuser",
    "created_at": "2023-03-01T22:51:57.700827",
    "updated_at": "2023-03-01T22:51:57.700842",
    "subscription": "https://stage.api.finexio.com/v1/webhooks/6c88d1f3-fddd-4a87-b49b-5c4371b61e14/",
    "username": "EnterUsernameHere",
    "password": "EnterPasswordHere"
}

Webhook Payload

Here is an example of the “payment.changed” event payload:

{
  "object_type": "payment",
  "object_id": "pmt_mnXYAtWkNQEGbOGoDaOFJDREAekAlZh",
  "event": "payment.changed"
}

After receiving the above payload, the object_id may be used with the Get Payment Detail API to get the payment information. The result of Get Payment Detail will have the originating_counterparty_id (Buyer) and receiving_counterparty_id (Supplier), which may be used with the Get Counterparty Detail API to get information about the Buyer and Supplier for this payment. Furthermore, the payment detail contains information about the invoice(s), including invoice ids which may be used with the Get Invoice Detail API to get the information about an invoice associated with that payment.

Webhook Headers

Here is an example of headers containing additional context that you may receive back with your payload.

authorization	Basic Zm9vOmJhcg==
hook-subscription	dae0652d-cee8-46a2-85aa-e0c819d827d2
hook-hmac	SAkyBVvRBVBfX884ZlWoGA/nTS3QU5HB5HhXOcdkTkunKqiTeORHkm3QDXwsgCk2ob2s0Pdy9KIq/9ki0/PJYg==
hook-delivery	f21afdc0-fcd5-4c56-a3a9-996d6ce3be96
hook-event	payment.changed
content-type	application/json