# Webhooks

Invunion POSTs a signed JSON envelope to your HTTPS URL when a subscribed event occurs. Choose event types per destination in Developer → Webhooks.

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

## What you will find here

An outbound webhook is a tenant-scoped HTTPS POST. Configure destinations in Developer → Webhooks. Each tenant may have up to five destinations.

## Events

A destination receives only the types you select.

### Transactions

- `transaction.created`

### Invoices

- `invoice.created`
- `invoice.updated`
- `invoice.paid`
- `invoice.partially_paid`

### Matching

- `match.created`
- `match.suggested`
- `match.confirmed`
- `match.rejected`
- `match.cancelled`

### Banking

- `bank.connected`
- `bank.disconnected`

### Synchronization

- `sync.completed`
- `sync.failed`

## Example payload

Invunion POSTs this envelope. `type` is the event name. `data` is the object for that event.

### Transaction created

```json
{
  "id": "9d7deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "transaction.created",
  "created_at": "2026-09-12T08:12:00.000Z",
  "data": {
    "transaction": {
      "id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
      "amount": 1000,
      "currency": "EUR",
      "direction": "in",
      "remainingAmount": 1000,
      "status": "unmatched",
      "source": {
        "type": "bank",
        "id": "6b4deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
      },
      "accountId": "0a8deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "counterpartyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "transactionDate": "2026-09-12T00:00:00.000Z"
    }
  }
}
```

### Invoice paid

```json
{
  "id": "7b5deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "invoice.paid",
  "created_at": "2026-09-12T09:00:03.000Z",
  "data": {
    "invoice": {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "number": "INV-2026-0042",
      "total": 12000,
      "settled": 12000,
      "open": 0,
      "recovery": 100,
      "status": "paid"
    }
  }
}
```

### Match created

```json
{
  "id": "8c6deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "match.created",
  "created_at": "2026-09-12T09:00:04.000Z",
  "data": {
    "match": {
      "id": "1c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "active",
      "type": "manual",
      "isAutomatic": false,
      "isAiScored": false,
      "confidence": {
        "score": 100,
        "band": "high"
      },
      "reasons": [],
      "matchedAmount": 1000,
      "source": {
        "transactionType": "bank",
        "matchMethod": "manual",
        "transactionId": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
        "pspEventId": null
      }
    },
    "invoice": {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "number": "INV-2026-0042",
      "total": 12000,
      "settled": 1000,
      "open": 11000,
      "recovery": 8.33,
      "status": "partial"
    },
    "transaction": {
      "id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
      "amount": 1000,
      "currency": "EUR",
      "remaining": 0,
      "status": "matched"
    }
  }
}
```

### Match suggested

```json
{
  "id": "ad8deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "match.suggested",
  "created_at": "2026-09-12T09:00:05.000Z",
  "data": {
    "match": {
      "id": "9fbe3506-5c28-41a3-ec25-32619d4fb7e5",
      "status": "pending_review",
      "type": "rule",
      "isAutomatic": true,
      "isAiScored": false,
      "confidence": {
        "score": 72,
        "band": "medium"
      },
      "reasons": [
        "amount_match",
        "date_proximity"
      ],
      "matchedAmount": 1000,
      "source": {
        "transactionType": "bank",
        "matchMethod": "rule",
        "transactionId": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
        "pspEventId": null
      }
    },
    "invoice": {
      "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "number": "INV-2026-0042",
      "total": 12000,
      "settled": 0,
      "open": 12000,
      "recovery": 0,
      "status": "unpaid"
    },
    "transaction": {
      "id": "2d0e6679-7425-40de-944b-e07fc1f90ae7",
      "amount": 1000,
      "currency": "EUR",
      "remaining": 1000,
      "status": "unmatched"
    }
  }
}
```

Each request also includes `x-invunion-event`, `x-invunion-event-id`, `x-invunion-delivery-id`, `x-invunion-attempt`, and `x-invunion-signature` (`t=UNIX_TIMESTAMP,v1=HEX_DIGEST`). The signed body is authoritative for the event id and type.