# List events

Read the webhook event feed by polling, in sequence order.

Returns the same envelopes that are posted to webhook destinations, oldest first by `sequence`. Use it to catch up after your receiver was down, to reconcile, or instead of webhooks when you cannot expose a URL.

Start with `since=0`, then pass `pagination.nextSince` as `since` until `pagination.hasMore` is false. Store the last `nextSince` and resume from it next time. `sequence` strictly increases per tenant but can have gaps. An overlap when resuming is harmless: deduplicate on the event `id`.

Events are recorded only while an active destination or an enabled notification rule is subscribed to their type. An event becomes readable about 15 seconds after it is created (`meta.settleSeconds`) and stays readable for at least 45 days (`meta.minRetentionDays`). Pagination sits next to `data`, not inside it.

## See also

- [Webhooks](https://www.invunion.com/knowledge-base/api/webhooks/). Event types and the payload of each.

- HTTP method: `GET`
- Path: `/api/v1/events`
- URL: `https://api.invunion.com/api/v1/events`
- Required scope: `events:read`
- HTML docs: https://www.invunion.com/knowledge-base/api/list-events/
- Markdown docs: https://www.invunion.com/knowledge-base/api/list-events.md


## Query parameters

| Name | Type | Required | Description | Allowed values | Example |
| --- | --- | --- | --- | --- | --- |
| `since` | string, no maximum | optional | Return events with a sequence strictly greater than this. Default 0 (from the oldest kept). |  | `1234500` |
| `limit` | integer | optional | Events per page. Default 100, maximum 500. |  | `100` |
| `type` | string, max 120 | optional | Only this event type, for example `invoice.settled`. An unknown type returns 400. |  | `invoice.settled` |


## Errors

| Error | HTTP code | Description |
| --- | --- | --- |
| `Missing Bearer token` | `401` | The Authorization header is missing or is not a Bearer token. |
| `Invalid or revoked API key` | `401` | The API key is unknown, malformed, expired, or has been revoked. |
| `API key is missing scope events:read` | `403` | The key does not include events:read. A write scope does not imply the matching read scope. |
| `Too many requests, please try again later` | `429` | More than 100 requests in one minute from this API key or IP address. Wait for the Retry-After header (seconds) and retry. |
| `Unknown event type: …` | `400` | type is not one of the event types listed on the Webhooks page. |
| `Invalid query parameters` | `400` | since is not a sequence number, or limit is outside 1 to 500. details lists field and message. |
| `Internal server error` | `500` | Unexpected server error. The JSON body includes correlationId. Retry with backoff. |

## Request (curl)

```bash
curl --request GET \
  --url https://api.invunion.com/api/v1/events?since=1234500&limit=100 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY'
```

## Request (Python)

```python
import requests

url = "https://api.invunion.com/api/v1/events?since=1234500&limit=100"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
}
response = requests.get(url, headers=headers)
print(response.json())
```

## Request (Ruby)

```ruby
require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.invunion.com/api/v1/events?since=1234500&limit=100")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Accept'] = 'application/json'
request['Authorization'] = 'Bearer uk_live_YOUR_API_KEY'
response = http.request(request)
puts response.body
```

## Request (JavaScript)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/events?since=1234500&limit=100", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY"
  },
});
const data = await response.json();
```

## Request (Go)

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest("GET", "https://api.invunion.com/api/v1/events?since=1234500&limit=100", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer uk_live_YOUR_API_KEY")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

## Request (Node)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/events?since=1234500&limit=100", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY"
  },
});
console.log(await response.json());
```

## Success (200)

```json
{
  "success": true,
  "data": [
    {
      "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"
        }
      }
    },
    {
      "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": []
      }
    }
  ],
  "pagination": {
    "nextSince": "1234567",
    "hasMore": false
  },
  "meta": {
    "minRetentionDays": 45,
    "settleSeconds": 15
  }
}
```