> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai2fin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks — events, payloads, signatures and retries

> The three 2Fin webhook events and the test ping, their JSON payloads, how to verify the X-AI2Fin-Signature header, the retry schedule, auto-disable, secret rotation and redelivery.

Webhooks send an HTTPS `POST` to your URL when something happens in your books, so a spreadsheet, an automation tool or your own service can follow along without polling. Webhooks are part of the **Auto+** plan.

The events, headers and payloads below are also published as an [AsyncAPI 3.0 document](https://docs.ai2fin.com/api-reference/asyncapi.json), so you can generate a typed handler or validate a delivery against it.

## Events

| Event | Sent when |
| - | - |
| `transaction.categorized` | Transactions finish categorisation, whether by your rules, recurring patterns, receipts or Fin's read. |
| `expense.created` | An expense is created in the app or through the Integration API (`POST /api/integrations/v1/expenses`). |
| `receipt.processed` | A receipt is committed. |
| `ping` | Only when you ask for a test delivery. |

The machine-readable definitions are in the `webhooks` section of the [OpenAPI document](https://docs.ai2fin.com/api-reference/openapi.json).

## Setting up a subscription

Two ways, with the same rules behind them:

* **In the app** (Settings → Automations), or with your session token at `/api/automations/webhooks`. This surface also pauses and resumes, rotates the secret, sends a test ping, lists deliveries and redelivers.
* **REST Hooks** for automation platforms, at `/api/integrations/v1/webhooks` with an OAuth token carrying `webhooks:manage`: list, subscribe and unsubscribe.

```bash theme={null}
curl -X POST https://api.ai2fin.com/api/automations/webhooks \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/ai2fin",
    "events": ["transaction.categorized", "expense.created"],
    "fieldFilter": ["description"],
    "consentAcknowledged": true
  }'
```

The `201` response carries `subscription` and `secret` (`whsec_…`). The secret is shown this once, so store it now.

* `consentAcknowledged` must be `true`. Show the person the consent text from `GET …/webhooks` first.
* The URL must be `https://` on port 443 with a DNS name. IP addresses, local or internal names, credentials in the URL, and names that resolve to private addresses are refused. The address is checked again on every delivery.
* An account can have up to 10 subscriptions.

## Payloads

Every event shares one envelope. Fields are kept to a minimum: the base fields below, plus any you opt into with `fieldFilter`.

```json theme={null}
{
  "event": "transaction.categorized",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-11-12T03:14:07.000Z",
  "data": {
    "id": "cmh1x2y3z0001ab12cd34ef56",
    "amount": -42.5,
    "date": "2026-11-10T00:00:00.000Z",
    "merchant": "Officeworks",
    "category": "Office Supplies",
    "source": "csv_import"
  }
}
```

| Field | Notes |
| - | - |
| `data.id` | The transaction, expense or receipt id. |
| `data.amount` | A number; money out is negative on transactions. Can be `null` on a receipt that had no readable total. |
| `data.date` | ISO 8601. |
| `data.merchant`, `data.category` | Can be `null`. `category` is always `null` on `expense.created` and `receipt.processed`. |
| `data.source` | Where the record came from: `bank_feed`, `csv_import`, `api` or `manual` on transactions; `manual` on expenses; `receipt` on receipts. |
| `data.description` | Only when the subscription opted into `description`, and only on transaction and expense events. |

`fieldFilter` accepts `description`, `reference` and `notes`; today only `description` appears in any event.

Transactions from connected bank feeds are included and marked `source: "bank_feed"`.

`ping` has no `apiVersion`: `{ "event": "ping", "createdAt": "…", "data": { "message": "AI2Fin webhook test delivery" } }`.

## Verifying the signature

Each delivery carries these headers:

| Header | Value |
| - | - |
| `X-AI2Fin-Signature` | `t=<unix seconds>,v1=<signature>`. The signature is the hex HMAC-SHA256 of `<t>.<raw body>` keyed with your secret. |
| `X-AI2Fin-Event` | The event name. |
| `X-AI2Fin-Delivery` | The delivery id. Automatic retries keep the same id, so use it to ignore repeats. |
| `User-Agent` | `AI2Fin-Webhooks/1.0 (+https://docs.ai2fin.com)` |

Check the signature against the raw bytes of the body, before parsing it, and reject timestamps more than five minutes from your clock.

```js Node.js theme={null}
import crypto from 'node:crypto';

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex'),
  );
  return header.split(',').some((part) => {
    if (!part.startsWith('v1=')) return false;
    const got = Buffer.from(part.slice(3));
    return got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}
```

```python Python theme={null}
import hashlib, hmac, re, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    m = re.search(r'(?:^|,)t=(\d+)', header)
    if not m or abs(time.time() - int(m.group(1))) > tolerance:
        return False
    t = m.group(1)
    expected = hmac.new(secret.encode(), t.encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return any(part.startswith('v1=') and hmac.compare_digest(part[3:], expected)
               for part in header.split(','))
```

Accept the delivery if any `v1=` value matches. After you rotate the secret, deliveries carry two `v1=` values (new and previous secret) for 24 hours, so you can switch your receiver over without missing anything. A second rotation is refused until that window has closed.

## Delivery and retries

* Answer with any `2xx` within 10 seconds. Anything else, or no answer, counts as a failure.
* A failed delivery is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours: six attempts in all over about seven hours. After the last it is marked dead.
* Eight dead deliveries in a row pause the subscription (`disabledReason: "auto_disabled_delivery_failures"`). Resume it from Automations, or with `PATCH /api/automations/webhooks/{id}` and `{ "active": true }`, which also resets the count.
* Deliveries are queued and usually sent within about 10 seconds of the event. Order is not guaranteed; use `createdAt` if order matters.
* Delivered and dead deliveries are kept for 30 days. `GET /api/automations/webhooks/{id}/deliveries` lists recent ones, and `POST …/deliveries/{deliveryId}/redeliver` sends one again (up to 7 days old, with a new delivery id).
* Pausing or deleting a subscription stops its deliveries at once, including any still waiting.

Treat webhooks as at-least-once: the same event can arrive more than once, so make your handler safe to run twice, keyed on `X-AI2Fin-Delivery` or `data.id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.