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",
  "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,
  "currency": string, // ISO 4217 currency code
  "institutionName": string | null, // the name of your bank
  "accountName": string,
  "updateType": "ADD" | "MODIFY",
  "type": "FULL"
}

• 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",
  "createdAt": string, // ISO 8601 timestamp string
  "updateType": "DELETE",
  "type": "REMOVED"
}

• 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

If your URL responds with a non-OK status (status NOT in the range 200-299), Finicom will automatically resend a webhook request again, up to 3 times, with an exponential backoff.

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

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.