# Webhooks

Get told when something changes in Invunion. Invunion sends a signed JSON event to your HTTPS URL for each event type you choose.

- HTML docs: https://www.invunion.com/knowledge-base/api/webhooks/
- Markdown docs: https://www.invunion.com/knowledge-base/api/webhooks.md

## Events

### Counterparties

- `counterparty.created`: a counterparty was created.
- `counterparty.updated`: a counterparty was changed.
- `counterparty.deleted`: a counterparty was deleted.

### Payment methods

Payment methods do not send events yet.

### Transactions

- `transaction.created`: a bank transaction was created, including one outside matching scope.
- `transaction.included`: a transaction entered the matching scope.
- `transaction.excluded`: a transaction left the matching scope.

### Invoices and credit notes

- `invoice.created`: an invoice or credit note was created.
- `invoice.updated`: an invoice or credit note was changed.
- `invoice.settlement_changed`: a payment, credit note, refund, or adjustment was added to or removed from the document.
- `invoice.settled`: nothing is left to pay on the document.

### Matching

- `match.created`: a payment was matched to an invoice.
- `match.suggested`: a match is waiting for review.
- `match.confirmed`: a suggested match was confirmed.
- `match.rejected`: a suggested match was rejected.
- `match.cancelled`: a match was cancelled.

### Banking

- `bank.connected`: a bank connection was established.
- `bank.disconnected`: a bank connection was lost.

### Synchronization

- `sync.completed`: a synchronization finished.
- `sync.failed`: a synchronization failed.

The older invoice events (`invoice.paid`, `invoice.partially_paid`, `invoice.fully_credited`, `invoice.partially_credited`, `invoice.mixed_settlement`, `credit_note.applied`, and `credit_note.refunded`) are no longer sent: a destination subscribed to any of them now receives `invoice.settlement_changed` and `invoice.settled`.

## Verify signatures

Each request carries `x-invunion-signature: t=UNIX_TIMESTAMP,v1=HEX_DIGEST`: an HMAC-SHA256 of `timestamp.rawBody` with the destination secret. Compute it on the exact raw body, before parsing the JSON, and reject a timestamp more than five minutes away.

## Delivery and retries

- At least once, with a 10-second deadline per request and no redirects.
- Retries after about 1 minute, 5 minutes, 30 minutes, 2 hours, and 6 hours.
- Answer `429` or `503` with `Retry-After` to pause the destination (up to six hours) without using up attempts. At most five requests run at a time per destination.
- A destination is disabled only after 20 deliveries used all their attempts over more than three days. Its alert addresses are mailed for the outcomes you choose: `failed`, `exhausted`, or `disabled`.
- The console delivery log shows each failure and its `failureKind`, and resends failed deliveries in bulk.

## Batch mode

Set a batch size (2 to 100) on a destination to receive several events per request, as `{ "type": "batch", "api_version", "created_at", "events": [...] }`, signed the same way. A `2xx` accepts the whole batch; any other answer retries all of it.

## Testing

In Developer → Webhooks, Send test posts an example of any event type with `"test": true` in the envelope.

## Catch up with the Events API

List events (`GET /api/v1/events`, scope `events:read`) returns the same envelopes in `sequence` order, kept for at least 45 days. Use it to recover events your server missed. Only event types that a destination or notification rule subscribes to are recorded.

## Examples

### Envelope

```json
{
  "id": "7b5deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "invoice.settled",
  "created_at": "2026-09-28T10:00:03.000Z",
  "sequence": 1234567,
  "data": {}
}
```

### Counterparty created

```json
{
  "id": "be9deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "counterparty.created",
  "created_at": "2026-09-12T09:10:00.000Z",
  "sequence": 1234510,
  "data": {
    "counterparty": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "accountCode": "CPT-042",
      "name": "Acme SAS",
      "displayName": "Acme",
      "category": "professional",
      "roles": {
        "client": true,
        "supplier": false,
        "partner": false,
        "payer": false,
        "internal": false,
        "employee": false
      },
      "vatNumber": "FR12345678901",
      "registrationNumber": "123456789",
      "externalReference": "CRM-88",
      "externalOrganizationId": null,
      "externalEntityId": null,
      "externalServiceId": null,
      "address": {
        "line": "1 rue de la Paix",
        "city": "Paris",
        "postalCode": "75002",
        "country": "FR"
      },
      "emails": [
        "billing@acme.example"
      ],
      "phone": "+33100000000",
      "paymentTermsDays": 30,
      "status": "up_to_date",
      "source": "manual",
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-20T09:00:00.000Z"
    }
  }
}
```

### Counterparty updated

```json
{
  "id": "cf0deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "counterparty.updated",
  "created_at": "2026-09-12T09:20:00.000Z",
  "sequence": 1234511,
  "data": {
    "counterparty": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "accountCode": "CPT-042",
      "name": "Acme SAS",
      "displayName": "Acme",
      "category": "professional",
      "roles": {
        "client": true,
        "supplier": false,
        "partner": false,
        "payer": false,
        "internal": false,
        "employee": false
      },
      "vatNumber": "FR12345678901",
      "registrationNumber": "123456789",
      "externalReference": "CRM-88",
      "externalOrganizationId": null,
      "externalEntityId": null,
      "externalServiceId": null,
      "address": {
        "line": "1 rue de la Paix",
        "city": "Paris",
        "postalCode": "75002",
        "country": "FR"
      },
      "emails": [
        "billing@acme.example"
      ],
      "phone": "+33100000001",
      "paymentTermsDays": 30,
      "status": "up_to_date",
      "source": "manual",
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-20T09:00:00.000Z"
    },
    "changedFields": [
      "phone"
    ],
    "previous": {
      "phone": "+33100000000"
    }
  }
}
```

### Transaction created

```json
{
  "id": "9d7deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "transaction.created",
  "created_at": "2026-09-12T08:12:00.000Z",
  "sequence": 1234501,
  "data": {
    "transaction": {
      "id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
      "code": "TX-8891",
      "scope": {
        "inScope": true,
        "reason": null,
        "source": null,
        "ruleId": null,
        "forcedInclude": false
      },
      "amount": "160.00",
      "currency": "EUR",
      "direction": "in",
      "flowType": "payment",
      "remainingAmount": "160.00",
      "status": "unconsidered",
      "source": {
        "type": "csv",
        "id": "6b4deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
      },
      "accountId": null,
      "ownAccountId": null,
      "counterpartyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "counterparty": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Acme SAS"
      },
      "transactionDate": "2026-09-28T00:00:00.000Z",
      "bookingDate": "2026-09-28T00:00:00.000Z",
      "valueDate": "2026-09-28T00:00:00.000Z",
      "externalReference": "BANK-2291",
      "structuredReference": null,
      "remittanceInfo": "INV-2026-0042",
      "description": "Virement Acme SAS"
    }
  }
}
```

### Transaction included

```json
{
  "id": "ee1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "transaction.included",
  "created_at": "2026-09-12T08:20:00.000Z",
  "sequence": 1234502,
  "data": {
    "transaction": {
      "id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
      "code": "TX-8891",
      "scope": {
        "inScope": true,
        "reason": null,
        "source": null,
        "ruleId": null,
        "forcedInclude": true
      },
      "amount": "160.00",
      "currency": "EUR",
      "direction": "in",
      "flowType": "payment",
      "remainingAmount": "160.00",
      "status": "unmatched",
      "source": {
        "type": "csv",
        "id": "6b4deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
      },
      "accountId": null,
      "ownAccountId": null,
      "counterpartyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "counterparty": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Acme SAS"
      },
      "transactionDate": "2026-09-28T00:00:00.000Z",
      "bookingDate": "2026-09-28T00:00:00.000Z",
      "valueDate": "2026-09-28T00:00:00.000Z",
      "externalReference": "BANK-2291",
      "structuredReference": null,
      "remittanceInfo": "INV-2026-0042",
      "description": "Virement Acme SAS"
    },
    "change": {
      "trigger": "manual",
      "previous": {
        "inScope": false,
        "reason": "payroll",
        "source": "rule"
      }
    }
  }
}
```

### Invoice settlement changed (first installment)

```json
{
  "id": "6a4deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "invoice.settlement_changed",
  "created_at": "2026-09-15T10:00:02.000Z",
  "sequence": 1234561,
  "data": {
    "invoice": {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "number": "INV-2026-0042",
      "total": "160.00",
      "totalExclVat": "133.33",
      "vatAmount": "26.67",
      "settled": "60.00",
      "open": "100.00",
      "recovery": "37.50",
      "status": "partial",
      "kind": "invoice",
      "currency": "EUR",
      "invoiceDate": "2026-09-01",
      "dueDate": "2026-10-01",
      "externalReference": "ERP-4521",
      "counterparty": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Acme SAS",
        "accountCode": "CPT-042",
        "externalReference": "CRM-88"
      },
      "settlement": {
        "status": "partial",
        "total": "160.00",
        "paid": "60.00",
        "credited": "0.00",
        "adjusted": "0.00",
        "open": "100.00"
      },
      "direction": "receivable",
      "parties": {
        "entity": {
          "identifiers": [
            {
              "type": "registration",
              "value": "987654321"
            },
            {
              "type": "vat",
              "value": "FR40987654321"
            }
          ]
        },
        "counterparty": {
          "identifiers": [
            {
              "type": "siren",
              "value": "123456789"
            },
            {
              "type": "vat",
              "value": "FR12345678901"
            }
          ]
        }
      }
    },
    "previous": {
      "status": "open",
      "total": "160.00",
      "paid": "0.00",
      "credited": "0.00",
      "adjusted": "0.00",
      "open": "160.00"
    },
    "change": {
      "added": [
        {
          "id": "9fbe3506-5c28-41a3-ec25-32619d4fb7e5",
          "type": "payment",
          "amount": "60.00",
          "currency": "EUR",
          "date": "2026-09-15",
          "allocatedAt": "2026-09-15T10:00:00.000Z",
          "payment": {
            "transactionId": "7d9c13e4-3a06-4f81-ca03-104f7b2d95c3",
            "transactionCode": "TX-8892",
            "pspEventId": null,
            "appliedAmount": "60.00",
            "amount": "60.00",
            "currency": "EUR",
            "allocated": "60.00",
            "remaining": "0.00",
            "ownAccount": {
              "id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
              "code": "PM-001",
              "name": "Main account",
              "iban": "FR7630006000011234567890189"
            }
          },
          "creditNote": null,
          "invoice": null,
          "adjustment": null,
          "tax": {
            "taxable": "50.00",
            "amount": "10.00",
            "basis": "pro_rata"
          }
        }
      ],
      "removed": []
    },
    "allocations": [
      {
        "id": "9fbe3506-5c28-41a3-ec25-32619d4fb7e5",
        "type": "payment",
        "amount": "60.00",
        "currency": "EUR",
        "date": "2026-09-15",
        "allocatedAt": "2026-09-15T10:00:00.000Z",
        "payment": {
          "transactionId": "7d9c13e4-3a06-4f81-ca03-104f7b2d95c3",
          "transactionCode": "TX-8892",
          "pspEventId": null,
          "appliedAmount": "60.00",
          "amount": "60.00",
          "currency": "EUR",
          "allocated": "60.00",
          "remaining": "0.00",
          "ownAccount": {
            "id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
            "code": "PM-001",
            "name": "Main account",
            "iban": "FR7630006000011234567890189"
          }
        },
        "creditNote": null,
        "invoice": null,
        "adjustment": null,
        "tax": {
          "taxable": "50.00",
          "amount": "10.00",
          "basis": "pro_rata"
        }
      }
    ],
    "relatedDocuments": []
  }
}
```

### Invoice settled (second installment)

```json
{
  "id": "7b5deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "invoice.settled",
  "created_at": "2026-09-28T10:00:03.000Z",
  "sequence": 1234567,
  "data": {
    "invoice": {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "number": "INV-2026-0042",
      "total": "160.00",
      "totalExclVat": "133.33",
      "vatAmount": "26.67",
      "settled": "160.00",
      "open": "0.00",
      "recovery": "100.00",
      "status": "paid",
      "kind": "invoice",
      "currency": "EUR",
      "invoiceDate": "2026-09-01",
      "dueDate": "2026-10-01",
      "externalReference": "ERP-4521",
      "counterparty": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Acme SAS",
        "accountCode": "CPT-042",
        "externalReference": "CRM-88"
      },
      "settlement": {
        "status": "settled",
        "total": "160.00",
        "paid": "160.00",
        "credited": "0.00",
        "adjusted": "0.00",
        "open": "0.00"
      },
      "direction": "receivable",
      "parties": {
        "entity": {
          "identifiers": [
            {
              "type": "registration",
              "value": "987654321"
            },
            {
              "type": "vat",
              "value": "FR40987654321"
            }
          ]
        },
        "counterparty": {
          "identifiers": [
            {
              "type": "siren",
              "value": "123456789"
            },
            {
              "type": "vat",
              "value": "FR12345678901"
            }
          ]
        }
      }
    },
    "previous": {
      "status": "partial",
      "total": "160.00",
      "paid": "60.00",
      "credited": "0.00",
      "adjusted": "0.00",
      "open": "100.00"
    },
    "change": {
      "added": [
        {
          "id": "1c9e6679-7425-40de-944b-e07fc1f90ae7",
          "type": "payment",
          "amount": "100.00",
          "currency": "EUR",
          "date": "2026-09-28",
          "allocatedAt": "2026-09-28T10:00:00.000Z",
          "payment": {
            "transactionId": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
            "transactionCode": "TX-8891",
            "pspEventId": null,
            "appliedAmount": "100.00",
            "amount": "100.00",
            "currency": "EUR",
            "allocated": "100.00",
            "remaining": "0.00",
            "ownAccount": {
              "id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
              "code": "PM-001",
              "name": "Main account",
              "iban": "FR7630006000011234567890189"
            }
          },
          "creditNote": null,
          "invoice": null,
          "adjustment": null,
          "tax": {
            "taxable": "83.33",
            "amount": "16.67",
            "basis": "pro_rata"
          }
        }
      ],
      "removed": []
    },
    "allocations": [
      {
        "id": "9fbe3506-5c28-41a3-ec25-32619d4fb7e5",
        "type": "payment",
        "amount": "60.00",
        "currency": "EUR",
        "date": "2026-09-15",
        "allocatedAt": "2026-09-15T10:00:00.000Z",
        "payment": {
          "transactionId": "7d9c13e4-3a06-4f81-ca03-104f7b2d95c3",
          "transactionCode": "TX-8892",
          "pspEventId": null,
          "appliedAmount": "60.00",
          "amount": "60.00",
          "currency": "EUR",
          "allocated": "60.00",
          "remaining": "0.00",
          "ownAccount": {
            "id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
            "code": "PM-001",
            "name": "Main account",
            "iban": "FR7630006000011234567890189"
          }
        },
        "creditNote": null,
        "invoice": null,
        "adjustment": null,
        "tax": {
          "taxable": "50.00",
          "amount": "10.00",
          "basis": "pro_rata"
        }
      },
      {
        "id": "1c9e6679-7425-40de-944b-e07fc1f90ae7",
        "type": "payment",
        "amount": "100.00",
        "currency": "EUR",
        "date": "2026-09-28",
        "allocatedAt": "2026-09-28T10:00:00.000Z",
        "payment": {
          "transactionId": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
          "transactionCode": "TX-8891",
          "pspEventId": null,
          "appliedAmount": "100.00",
          "amount": "100.00",
          "currency": "EUR",
          "allocated": "100.00",
          "remaining": "0.00",
          "ownAccount": {
            "id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
            "code": "PM-001",
            "name": "Main account",
            "iban": "FR7630006000011234567890189"
          }
        },
        "creditNote": null,
        "invoice": null,
        "adjustment": null,
        "tax": {
          "taxable": "83.33",
          "amount": "16.67",
          "basis": "pro_rata"
        }
      }
    ],
    "relatedDocuments": []
  }
}
```

### Match created

```json
{
  "id": "8c6deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "match.created",
  "created_at": "2026-09-12T09:00:04.000Z",
  "sequence": 1234505,
  "data": {
    "match": {
      "id": "1c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "confirmed",
      "type": "manual",
      "decision": "manual",
      "isAutomatic": false,
      "isAiScored": false,
      "confidence": {
        "score": 91,
        "band": "high"
      },
      "reasons": [
        "amount_exact",
        "reference_match"
      ],
      "matchedAmount": "160.00",
      "source": {
        "transactionType": "bank",
        "matchMethod": "manual",
        "transactionId": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
        "transactionCode": "TX-8891",
        "pspEventId": null
      }
    },
    "invoice": {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "number": "INV-2026-0042",
      "total": "160.00",
      "settled": "160.00",
      "open": "0.00",
      "recovery": "100.00",
      "status": "paid",
      "currency": "EUR"
    },
    "transaction": {
      "id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
      "code": "TX-8891",
      "amount": "160.00",
      "currency": "EUR",
      "remaining": "0.00",
      "status": "matched"
    }
  }
}
```

### Match suggested

```json
{
  "id": "ad8deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "api_version": "2026-10-15",
  "type": "match.suggested",
  "created_at": "2026-09-12T09:00:05.000Z",
  "sequence": 1234506,
  "data": {
    "match": {
      "id": "1c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "pending_review",
      "type": "rule",
      "decision": "pending_review",
      "isAutomatic": true,
      "isAiScored": false,
      "confidence": {
        "score": 62,
        "band": "medium"
      },
      "reasons": [
        "amount_exact",
        "reference_match"
      ],
      "matchedAmount": "160.00",
      "source": {
        "transactionType": "bank",
        "matchMethod": "rule",
        "transactionId": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
        "transactionCode": "TX-8891",
        "pspEventId": null
      }
    },
    "invoice": {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "number": "INV-2026-0042",
      "total": "160.00",
      "settled": "160.00",
      "open": "0.00",
      "recovery": "100.00",
      "status": "paid",
      "currency": "EUR"
    },
    "transaction": {
      "id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
      "code": "TX-8891",
      "amount": "160.00",
      "currency": "EUR",
      "remaining": "0.00",
      "status": "matched"
    }
  }
}
```