Webhook Destination

Intro

Finicom's Webhook destination allows your application or server to receive updates on transactions that occur on your Bank account.

Finicom will automatically make POST requests to the URL of your choosing whenever financial transactions are updated on your accounts.

Creating a Webhook Destination

1. Go to your organization's destination page
2. Click "Add Destination"
3. Click "Webhook"
4. Complete adding details for your new webhook destination, including which source to use, and which URL to send requests to.
5. Click "Create Destination"

Details

Webhook requests are:

• sent via HTTP POST
• sent once per transaction update
• always have the user agent Finicom/Webhook/1.0, though this is subject to change if versions change
• have JSON bodies with Content-Type=application/json
• request bodies for added and modified transactions have the following shape and types:

{
  "id": string, // the unique identifier of this transaction
  "status": "pending" | "posted", // The current state of the transaction in the financial system
  "createdAt": string, // ISO 8601 timestamp string
  "merchant": string | null, // the merchant who the transaction was with
  "description": string | null, // the description of the transaction from your bank
  "accountId": string, // the Id of your bank account
  "amount": number, // the transaction amount in the specified currency (positive for deposits, negative for withdrawals)
  "currency": string, // ISO 4217 currency code
  "institutionName": string | null, // the name of your bank
  "accountName": string, // the name of your bank account source in Finicom
  "category": string | null, // the category of the transaction, like "TRANSPORTATION_GAS", "TRANSFER_IN_DEPOSIT", and many more
  "updateType": "ADD" | "MODIFY", // indicates if this transaction update was a newly added transaction ("ADD") or an update to an existing transaction
  "type": "FULL" // always "FULL" for ADD and MODIFY transaction updates since transaction data is included
}

• since Finicom does not store your transaction information, request bodies for removed transactions have the following shape and types:

{
  "id": string, // the unique identifier of this transaction
  "accountId": string, // the Id of your bank account
  "status": "void", // the current state of the transaction in the financial system; will always be void as this deleted transaction has been voided
  "createdAt": string, // ISO 8601 timestamp string
  "updateType": "DELETE",// indicates if this transaction update was a removal of an existing transaction and should be deleted from the system
  "type": "REMOVED" // always "REMOVED" for DELETE transaction updates since transaction data is not included
}

• the updateType key can be used to know which action to take in your system. For example, if you receive an updateType of MODIFY, the transaction with that id in your system should be modified to have the new data provided in the request body of that webhook

We intend to allow customization via templating of request bodies. If this is something that interests you, please let us know at [email protected]

Error Handling

If your URL responds with a non-OK status (status NOT in the range 200-299), Finicom will immediately resend a webhook request again, up to 3 times, with an exponential backoff. If each of these 3 immediate retries fails, Finicom will automatically retry the webhook request daily, for up to 60 days. After 60 days of failures, the transaction update is considered failed and will not be retried.

For error visibility, the last error response code will be shown on the destination's detail page. Any successful webhooks requests after this will clear this error from being shown. If your destination continually has errors for 7 days, it will be paused automatically.

Finicom intelligently handles transaction update sequences to minimize unnecessary API calls. If a transaction update (such as ADD) is still failed, and a newer update for the same transaction arrives (such as DELETE), Finicom will:

1. Skip the older, obsolete update (the ADD in this example)
2. Only send the most recent, relevant update (the DELETE)

This "obsolete update skipping" ensures your systems only receive the most current transaction state, reducing processing overhead and preventing confusing sequences like adding and immediately deleting the same transaction.

Advanced Usage

Finicom goes to great lengths to ensure every transaction sync happens only one time. In case Finicom ever sends webhook API calls twice for the same transaction update, Finicom's webhook requests include an Idempotency-Key header. Idempotency-Key headers are unique for every transaction update sync and are always the same for every instance of the same sync on a single destination. To ensure webhook updates are applied exactly once in your system, your system should read the idempotency key and only apply any the webhook update if the idempotency key has not been seen before by your system. Your system should temporarily store this idempotency key after processing the webhook request to be able to check it later.