Webhooks
Get told when something changes in Invunion. Invunion sends a signed JSON event to your HTTPS URL for each event type you choose.
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
429or503withRetry-Afterto 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, ordisabled. - 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
{
"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
200
{
"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": [
"[email protected]"
],
"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
200
{
"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": [
"[email protected]"
],
"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
200
{
"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
200
{
"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)
200
{
"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)
200
{
"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
200
{
"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
200
{
"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"
}
}
}