The Events API provides a read-only audit trail of everything that happens in your account. Use it to inspect event history, debug webhook delivery issues, and build event timelines for individual entities.

Events are automatically generated whenever a state change occurs in PaymentKit — when an invoice is paid, a subscription is created, or a customer is updated. They are the same events that drive webhook delivery.

Event object

Each event captures a single state change. An event always belongs to one entity (aggregate_id) and carries a full snapshot of the entity’s state before and after the change.

Field	Type	Description
`id`	string	Unique event identifier (e.g., `evt_prod_a1b2c3d4e5f6g7h8`)
`type`	string	Event type (e.g., `invoice.paid`, `customer.subscription.created`)
`aggregate_type`	string	Entity type the event belongs to (e.g., `invoice`, `subscription`, `customer`)
`aggregate_id`	string	External ID of the entity this event relates to
`data`	object	Full entity state after the change
`previous_data`	object \| null	Full entity state before the change; `null` for create events
`metadata`	object	Additional event-specific metadata
`correlation_id`	string \| null	Request correlation ID for distributed tracing
`version`	integer	Schema version for event format evolution
`created`	datetime	When the event occurred (ISO 8601)
`actor_type`	string \| null	Type of actor who triggered the event: `user`, `api_key`, `system`, or `customer`
`actor_id`	string \| null	External ID of the actor who triggered the event

1 {
2   "id": "evt_prod_a1b2c3d4e5f6g7h8",
3   "type": "invoice.paid",
4   "aggregate_type": "invoice",
5   "aggregate_id": "in_prod_a1b2c3d4e5f6g7h8",
6   "data": {
7     "id": "in_prod_a1b2c3d4e5f6g7h8",
8     "status": "paid",
9     "currency": "usd",
10     "total_amount_atom": 290000,
11     "due_amount_atom": 0,
12     "paid_amount_atom": 290000
13   },
14   "previous_data": {
15     "id": "in_prod_a1b2c3d4e5f6g7h8",
16     "status": "open",
17     "currency": "usd",
18     "total_amount_atom": 290000,
19     "due_amount_atom": 290000,
20     "paid_amount_atom": 0
21   },
22   "metadata": {},
23   "correlation_id": "req_a1b2c3d4",
24   "version": 1,
25   "created": "2024-01-01T00:00:00Z",
26   "actor_type": "system",
27   "actor_id": null
28 }

Both data and previous_data contain the full entity state at the time of the event. previous_data is null for create events.

List events

Retrieve a paginated list of events for your account. Results are ordered by created descending (newest first).

$ curl https://api.paymentkit.com/api/{account_id}/events \
>   -H "Authorization: Bearer st_prod_..."

Filters

Use query parameters to narrow results:

Parameter	Type	Description
`event_id`	string	Fetch a specific event by its ID
`aggregate_id`	string	Show all events for a specific entity (e.g., invoice timeline)
`aggregate_type`	string	Show events for a type of entity (e.g., `invoice`, `subscription`)
`event_type`	string	Show events of a specific type (e.g., `invoice.paid`)

Results are ordered by created_at descending (newest first).

$ # All events for a specific invoice
$ curl "https://api.paymentkit.com/api/{account_id}/events?aggregate_id=in_prod_a1b2c3d4e5f6g7h8" \
>   -H "Authorization: Bearer st_prod_..."
$ 
$ # All subscription events
$ curl "https://api.paymentkit.com/api/{account_id}/events?aggregate_type=subscription" \
>   -H "Authorization: Bearer st_prod_..."
$ 
$ # All invoice.paid events
$ curl "https://api.paymentkit.com/api/{account_id}/events?event_type=invoice.paid" \
>   -H "Authorization: Bearer st_prod_..."

Get an event

Retrieve a single event by its ID.

$ curl https://api.paymentkit.com/api/{account_id}/events/evt_prod_a1b2c3d4e5f6g7h8 \
>   -H "Authorization: Bearer st_prod_..."

Returns the full Event object, or 404 if not found.

Event deliveries

Events are delivered to your webhook endpoints asynchronously. The delivery endpoints let you inspect the delivery status of any event across all your configured endpoints.

Delivery object

Field	Type	Description
`id`	string	Unique delivery identifier (e.g., `ed_prod_a1b2c3d4e5f6g7h8`)
`event_id`	string	ID of the event being delivered
`webhook_endpoint_id`	string	ID of the target webhook endpoint
`webhook_endpoint_url`	string \| null	URL of the target webhook endpoint
`status`	string	Delivery status: `pending`, `delivering`, `delivered`, or `failed`
`attempt_count`	integer	Number of delivery attempts made so far
`last_attempt_at`	datetime \| null	When the most recent delivery attempt occurred
`delivered_at`	datetime \| null	When the event was successfully acknowledged (2xx response)
`next_retry_at`	datetime \| null	When the next retry will be attempted; `null` if not scheduled
`response_status`	integer \| null	HTTP status code returned by your endpoint
`error`	string \| null	Error message if the last attempt failed
`created`	datetime	When this delivery record was created

List deliveries for an event

Returns all webhook delivery records for a specific event — one record per subscribed webhook endpoint.

$ curl https://api.paymentkit.com/api/{account_id}/events/evt_prod_a1b2c3d4e5f6g7h8/deliveries \
>   -H "Authorization: Bearer st_prod_..."

1 [
2   {
3     "id": "ed_prod_a1b2c3d4e5f6g7h8",
4     "event_id": "evt_prod_a1b2c3d4e5f6g7h8",
5     "webhook_endpoint_id": "whe_prod_a1b2c3d4e5f6g7h8",
6     "webhook_endpoint_url": "https://your-server.com/webhooks",
7     "status": "delivered",
8     "attempt_count": 1,
9     "last_attempt_at": "2024-01-01T00:00:05Z",
10     "delivered_at": "2024-01-01T00:00:05Z",
11     "next_retry_at": null,
12     "response_status": 200,
13     "error": null,
14     "created": "2024-01-01T00:00:00Z"
15   }
16 ]

Get event with deliveries

Retrieve an event together with all its delivery records in a single request, instead of calling the event and deliveries endpoints separately.

$ curl https://api.paymentkit.com/api/{account_id}/events/evt_prod_a1b2c3d4e5f6g7h8/full \
>   -H "Authorization: Bearer st_prod_..."

1 {
2   "event": {
3     "id": "evt_prod_a1b2c3d4e5f6g7h8",
4     "type": "invoice.paid",
5     "aggregate_type": "invoice",
6     "aggregate_id": "in_prod_a1b2c3d4e5f6g7h8",
7     "data": { ... },
8     "previous_data": { ... },
9     "metadata": {},
10     "correlation_id": "req_a1b2c3d4",
11     "version": 1,
12     "created": "2024-01-01T00:00:00Z",
13     "actor_type": "system",
14     "actor_id": null
15   },
16   "deliveries": [
17     {
18       "id": "ed_prod_a1b2c3d4e5f6g7h8",
19       "event_id": "evt_prod_a1b2c3d4e5f6g7h8",
20       "webhook_endpoint_id": "whe_prod_a1b2c3d4e5f6g7h8",
21       "webhook_endpoint_url": "https://your-server.com/webhooks",
22       "status": "delivered",
23       "attempt_count": 1,
24       "last_attempt_at": "2024-01-01T00:00:05Z",
25       "delivered_at": "2024-01-01T00:00:05Z",
26       "next_retry_at": null,
27       "response_status": 200,
28       "error": null,
29       "created": "2024-01-01T00:00:00Z"
30     }
31   ]
32 }

Use /full when debugging a specific event — it gives you the full event payload and all delivery outcomes in one request.