> For the complete documentation index, see [llms.txt](https://docs.tiun.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiun.io/reference/webhooks/events.md).

# Events

tiun sends a webhook event to your endpoints whenever one of the events below happens. Events are deliberately small: they tell you **what happened and to whom**, using IDs only. To get the current details — email, product access — your backend calls the tiun API with those IDs.

For setup and a full handler example, see [receiving webhooks](https://docs.tiun.io/guides/webhooks/receive-webhooks.md). For retries and timeouts, see [Webhook delivery](https://docs.tiun.io/reference/webhooks/delivery.md).

***

## Event types

| Event                   | When it's sent                                |
| ----------------------- | --------------------------------------------- |
| `user.create`           | A user signs up with you.                     |
| `user.revoke_consent`   | A user withdraws their consent to your terms. |
| `product_access.add`    | A user gains access to a product.             |
| `product_access.remove` | A user loses access to a product.             |

You choose which of these each endpoint receives when you add or edit it in the dashboard.

***

## The event envelope

Every event has the same shape. Only `payload` changes between event types.

```json
{
  "id": "b0c22a9741be458fa36e742d3d3bb0e8",
  "type": "product_access.add",
  "version": 1,
  "occurred_at": "2026-10-30T14:45:50.6090416+00:00",
  "payload": {
    "user_id": "user-sample-0001",
    "product_id": "product-sample-0001",
    "reference": null
  }
}
```

| Field         | Type     | Description                                                                                                            |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `id`          | `string` | Unique ID of the event. It stays the same across retries and resends, so use it to skip events you've already handled. |
| `type`        | `string` | The event type, for example `product_access.add`.                                                                      |
| `version`     | `number` | Version of the event's format. Currently always `1`.                                                                   |
| `occurred_at` | `string` | When the event happened, as an ISO 8601 timestamp in UTC.                                                              |
| `payload`     | `object` | The IDs involved. Depends on `type` — see below.                                                                       |

IDs in the payload belong to the environment the endpoint is set up in: a sandbox endpoint only receives sandbox users and products, and a live endpoint only live ones.

{% hint style="warning" %}
Webhooks aren't signed, so your endpoint can't tell a real tiun event from a forged one by looking at it. Treat every event as a **prompt to check**, and confirm the current state with an authenticated API call — for example the [UserInfo API](https://docs.tiun.io/guides/authentication/get-user-info.md) — before you act.
{% endhint %}

***

## User events

### `user.create`

Sent when a user signs up with you, usually at sign-in or checkout.

```json
{
  "id": "57ae16589e12424b9bef36eac8520a45",
  "type": "user.create",
  "version": 1,
  "occurred_at": "2026-11-01T13:15:25.493161+00:00",
  "payload": {
    "user_id": "user-sample-0001"
  }
}
```

| Field             | Type     | Description                                 |
| ----------------- | -------- | ------------------------------------------- |
| `payload.user_id` | `string` | The tiun user ID of the user who signed up. |

Use it to create the matching record in your own database, or to send a welcome email. Fetch the user's email and access with the [UserInfo API](https://docs.tiun.io/guides/authentication/get-user-info.md).

### `user.revoke_consent`

Sent when a user withdraws their consent to your terms.

```json
{
  "id": "e4a1f0c7b2d94b8a9c3f5e6d7a8b9c0d",
  "type": "user.revoke_consent",
  "version": 1,
  "occurred_at": "2026-11-02T09:21:58.3741652+00:00",
  "payload": {
    "user_id": "user-sample-0001"
  }
}
```

| Field             | Type     | Description                                        |
| ----------------- | -------- | -------------------------------------------------- |
| `payload.user_id` | `string` | The tiun user ID of the user who withdrew consent. |

When you receive it, **remove or anonymize the data you hold about that user** in your own systems, in line with your privacy obligations.

***

## Product access events

These events follow the same `productAccess` array the SDK and the UserInfo API expose. See [Product access](https://docs.tiun.io/reference/checkout/product-access.md) for when access changes.

### `product_access.add`

Sent when a user gains access to a product — for example after a completed one-time purchase, each purchase of a repeatable product, or when a subscription starts. Subscription renewals don't send it again: the user already has access.

```json
{
  "id": "b0c22a9741be458fa36e742d3d3bb0e8",
  "type": "product_access.add",
  "version": 1,
  "occurred_at": "2026-10-30T14:45:50.6090416+00:00",
  "payload": {
    "user_id": "user-sample-0001",
    "product_id": "product-sample-0001",
    "reference": "article-sample-0001"
  }
}
```

This example is a [repeatable product](https://docs.tiun.io/guides/one-time-purchases/repeatable-one-time-purchases.md), so `reference` carries the `referenceId` your app passed to checkout. For regular products it's `null`.

### `product_access.remove`

Sent when a user loses access to a product — for example when a subscription ends after a cancellation or a permanent payment failure, or when a one-time product with limited access reaches its end date.

```json
{
  "id": "77f57a6d684347efaf589c65d1d37d96",
  "type": "product_access.remove",
  "version": 1,
  "occurred_at": "2026-11-01T11:13:37.8045069+00:00",
  "payload": {
    "user_id": "user-sample-0001",
    "product_id": "product-sample-0001",
    "reference": null
  }
}
```

Both events share the same payload:

| Field                | Type             | Description                                                                                                                                                                               |
| -------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payload.user_id`    | `string`         | The tiun user ID whose access changed.                                                                                                                                                    |
| `payload.product_id` | `string`         | The product the access is for.                                                                                                                                                            |
| `payload.reference`  | `string \| null` | For [repeatable products](https://docs.tiun.io/guides/one-time-purchases/repeatable-one-time-purchases.md), the `referenceId` the purchase was made with. `null` for every other product. |

When either event arrives, confirm the change with the API before you update your own records — don't add or remove access based on the event alone:

* **`reference` is `null`** — re-read the user's `productAccess` with the [UserInfo API](https://docs.tiun.io/guides/authentication/get-user-info.md).
* **`reference` is set** — check that one purchase with `GET /live_api/s2s/v1/users/{userId}/product_access/{productId}?referenceId={reference}`. See [verifying repeatable purchases server-side](https://docs.tiun.io/guides/one-time-purchases/verify-server-side.md).

***

## Where to go next

* [Webhook delivery](https://docs.tiun.io/reference/webhooks/delivery.md) — retries, timeouts, and delivery statuses.
* [Receiving webhooks](https://docs.tiun.io/guides/webhooks/receive-webhooks.md) — set up an endpoint and handle events end to end.
* [User object](https://docs.tiun.io/reference/authentication/user-object.md) — the fields behind `user_id` and `productAccess`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tiun.io/reference/webhooks/events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
