# Webhooks

Instant posts each event to the integrator's webhook as a `POST`. Each kind has its headers, payload and answer.

## Kinds

### `approval.due`

A member's turn to approve

It is a member's turn in an approval round, or a scheduled run waits for its owner's approval. item is the subject's, usually a document, partner, payment or run. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: approval.due`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `approval.due`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `browser.takeover_needed`

Reserved: not sent yet

Reserved for a later use: Instant does not send this kind yet. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: browser.takeover_needed`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `browser.takeover_needed`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `connection.expired`

A bank consent ran out

A bank consent ran out. item is the bank_connection; there is no member. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: connection.expired`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `connection.expired`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `connection.synced`

A bank backfill or asked read ended

A bank connection's read ended: from its first day after the consent, again when a new or rediscovered account or an earlier first day needs a first-day read, or a read the member asked for. item is the bank_connection with outcome completed or failed; there is no member. Routine reads send nothing. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: connection.synced`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `connection.synced`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `customer.paused`

A customer was paused

The integrator paused the customer. item is the customer; there is no member. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: customer.paused`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `customer.paused`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `customer.resumed`

A customer was resumed

The integrator resumed the customer. item is the customer; there is no member. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: customer.resumed`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `customer.resumed`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `docs.updated`

The docs changed

A production release changed a reference or a guide: this API's or the customer API's. Sent to every active integrator with a webhook, at most once an hour; changes in the meantime go out together. changed names each part that changed, its new version (its ETag without the quotes) and the URL to fetch it with the integrator credential. Like every kind it is delivered at least once: deduplicate on Instant-Event-Id. A rollback that changes what Instant serves is announced like any other change, so a version can be announced again. It concerns no customer. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: docs.updated`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `docs.updated`): The kind of the event.

#### Payload

`application/json`, required: object; `DocsUpdatedPayload`

What a docs.updated delivery posts: the docs that changed, each with its new version and where to fetch it. It concerns no customer. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; always `docs.updated`): docs.updated, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When Instant announced the change. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `changed` (array of object; required; 1 to 4 items): Each part that changed: one to four, and no api and doc twice.
  - `api` (string; required; one of `integrator`, `customer`): Whose docs: integrator for this API's, customer for the customer API's.
  - `doc` (string; required; one of `openapi`, `guide`): openapi for the OpenAPI reference, guide for the guide.
  - `version` (string; required; matches `^[0-9a-f]{64}$`): The part's new version: the SHA-256 of the file in hex, which is its ETag without the quotes.
  - `url` (string; required): Where to fetch it with the integrator credential: readOpenApi or readGuide, with api=customer for the customer API's.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "docs.updated",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "changed": [
    {
      "api": "integrator",
      "doc": "openapi",
      "version": "string",
      "url": "string"
    }
  ]
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `link.finished`

A bank link ended

A bank connection link ended, once for each link: its consent gave a connection, the person cancelled, the bank or Instant could not complete it, or it expired. item is the bank_link with its outcome; there is no member. Like every kind it can arrive late, or after a later delivery. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: link.finished`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `link.finished`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `ping.raised`

A notice to a member

Any other notice to a member. item is its subject, or ping. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: ping.raised`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `ping.raised`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `reply.ready`

A chat reply is ready

A member's chat reply is recorded: one per reply, with the reply's message id as the delivery's id. item is the thread. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: reply.ready`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `reply.ready`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `run.finished`

Background work finished

Background work or a recurring action finished for its owner. item is the run. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: run.finished`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `run.finished`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

### `task.input_needed`

A task needs its owner

A follow-up task stopped for its owner. item is the task. A receiver ignores an event kind it does not know: kinds are added over time.

`Instant-Event-Kind: task.input_needed`

#### Headers

- `Instant-Signature` (string; required): `t=<unix seconds>,v1=<hex>`: t is when this attempt was sent, so each retry is signed again, and v1 is the HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook secret string as sent to you (not hex-decoded). Reject a t more than 5 minutes off.
- `Instant-Event-Id` (string · uuid; required): The same on every attempt of one event: delivery is at least once.
- `Instant-Event-Kind` (string; required; always `task.input_needed`): The kind of the event.

#### Payload

`application/json`, required: object; `WebhookPayload`

What a delivery posts: ids and the integrator's own references, never a text, a title, a path, an amount or an approval code. At most 2048 bytes.

- `id` (string · uuid; required): The event's id, the same on every attempt and in Instant-Event-Id: deduplicate on it.
- `kind` (string; required; one of `reply.ready`, `run.finished`, `approval.due`, `task.input_needed`, `ping.raised`, `browser.takeover_needed`, `connection.expired`, `customer.paused`, `customer.resumed`, `connection.synced`, `link.finished`): The kind, also in Instant-Event-Kind.
- `occurredAt` (string · date-time; required): When it happened. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- `customerId` (string · uuid; required): The customer it is about.
- `customerReference` (string; required; 1 to 200 characters): The integrator's reference for the customer.
- `memberId` (string · uuid): The member it is for; absent for connection.expired, connection.synced, link.finished, customer.paused and customer.resumed.
- `memberReference` (string; 1 to 200 characters): The integrator's reference for the member; absent when memberId is.
- `item` (one of 4 shapes; required): What the event is about. Read it through the customer API, as the member.
  - either object
    - `kind` (string; required; always `run`)
    - `actionId` (string · uuid; required): The recurring action or background work.
    - `runId` (string · uuid; required): The run.
  - or object
    - `kind` (string; required; one of `approval`, `task`, `ping`, `document`, `partner`, `payment`, `thread`, `customer`, `bank_connection`)
    - `id` (string · uuid): The subject's id; absent when it is not a UUID.
  - or object
    - `kind` (string; required; always `bank_connection`)
    - `id` (string · uuid; required): The bank connection.
    - `outcome` (string; required; one of `completed`, `failed`): connection.synced only: completed when every account was read (from the first day through yesterday for a backfill); failed when the consent ran out first, or a read asked for failed.
  - or object
    - `kind` (string; required; always `bank_link`)
    - `id` (string · uuid; required): The bank connection link.
    - `outcome` (string; required; one of `connected`, `cancelled`, `failed`, `expired`): link.finished only: connected when the consent gave a connection; cancelled when the person cancelled; failed when the bank or its provider refused, or Instant could not complete the consent; expired when nobody opened the link in time, or its consent never came back.
- `pingId` (string · uuid): The notice that made it; only for approval.due, run.finished, task.input_needed and ping.raised.

Example, built from the schema:

```json
{
  "id": "01900000-0000-7000-8000-000000000000",
  "kind": "reply.ready",
  "occurredAt": "2026-01-15T09:30:00.000Z",
  "customerId": "01900000-0000-7000-8000-000000000000",
  "customerReference": "string",
  "memberId": "01900000-0000-7000-8000-000000000000",
  "memberReference": "string",
  "item": {
    "kind": "run",
    "actionId": "01900000-0000-7000-8000-000000000000",
    "runId": "01900000-0000-7000-8000-000000000000"
  },
  "pingId": "01900000-0000-7000-8000-000000000000"
}
```

#### Answer

##### 2XX

Received. Any other answer, or none within 10 s, is retried; 7 attempts.

No body.

---

Page: https://booksbyinstant.com/docs/webhooks/ · Overview: https://booksbyinstant.com/docs/index.md