Webhook Destination

Intro

Finicom's

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 have the following shape and types:

{
  id: string,
  accountId: string | null, // the Id of your bank account in Mercury
  vendor: "MERCURY",
  amount: number | null,
  description: string | null, // the description of the transaction from your bank
  currency: string | null, // ISO 4217 currency code
  status: "pending" | "posted" | "void",
  createdAt: date,
}

In rare cases where transactions are completely deleted from your bank, the status will be void and accountId, vendor, amount, description, and currency will be null. This is because Finicom never stores your transaction data and does not have this information when transactions are deleted.

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

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.