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.

Webhooks are payment based, so each new payment will trigger a single webhook and each new payment event (update) for an existing payment will also trigger a single webhook 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",
    "invoice_ids": false,
    "payment_status": false,
    "payment_events": false,
    "refund_reason": false,
    "instrument_number": false,
    "all_payment_details": false
}

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",
    "invoice_ids": false,
    "payment_status": false,
    "payment_events": false,
    "refund_reason": false,
    "instrument_number": false,
    "all_payment_details": false
}

Webhook Payload

Here is an example of the minimal “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 Expanded Payloads

Webhooks can be configured to expand the amount of information delivered about the payment. The Webhooks API includes flags for defining what expanded payload options you want included in your subscription.

invoice_ids - Set to true to receive an invoice_ids key in your webhook payload. This key is an array of strings of the id of each invoice included in the payment.
payment_status - Set to true to receive a payment_status key in your webhook payload. This key will have a string value matching the current status of the payment as it would be reported when performing a GET /v2/payments/{payment_id}.
payment_events - Set to true to receive a payment_events key in your webhook payload. This key will be an array of objects representing all of the events that have happened on the payment.
refund_reason - Set to true to receive a refund_reason key in your webhook payload. If the payment has been refunded the value for this key will contain a plain text reason a refund was issued.
instrument_number - Set to true to receive a instrument_number key in your webhook payload. This value will match the instrument_number received in the response when performing a GET /v2/payments/{payment_id}.
all_payment_details - Set to true to receive an object key in your webhook payload. If this expansion is enabled, all other expansions will not be sent. This expansion will send you the entire response body in the object key of performing a GET /v2/payments/{payment_id} for the 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