# Event types & payloads

> The event envelope, the request headers, and a full JSON example of every webhook event.

Every webhook request has the same envelope: an event `id`, its `type`, when it was created, and a `data` object whose shape depends on the type. New fields may be added to `data` over time, so ignore fields you do not recognize. The body is compact JSON whose key order is not specified; the examples below are formatted for reading. All ids are opaque strings: compare them, do not parse them.

| Type | Sent when |
| --- | --- |
| `database.created` | The first release of a database is ready to download. |
| `database.updated` | A new release of the database is ready (for example after a refresh, a field upgrade or a rebuild). Only sent when the release actually changed. |
| `database.build_failed` | A build did not complete. The current release, if any, stays available. |
| `webhook.test` | A test event sent to one endpoint from the dashboard's **Send test event** or the [test route](https://ipscope.io/docs/webhooks/api#send-a-test-event). |

## The event envelope

- `id` (string, required): Unique event id, starting with `evt_`. Equal to the `IPScope-Event-Id` header and the same on every retry: use it to deduplicate.
- `object` (string, required): Always `"event"`.
- `type` (string, required): The event type, such as `database.updated`. Equal to the `IPScope-Event-Type` header.
- `api_version` (string, required): The payload version, currently `"2026-11-04"`.
- `created_at` (string, required): When the event happened, as an ISO 8601 UTC timestamp.
- `data` (object, required): The event's details, described below for each type.

## Request headers

| Header | Example | Meaning |
| --- | --- | --- |
| `IPScope-Signature` | `t=1793761929,v1=d48dd8…` | Timestamp and HMAC-SHA256 signature of the request ([verifying](https://ipscope.io/docs/webhooks/verifying)). |
| `IPScope-Event-Id` | `evt_8f0c2e5d9b1a4c7e8f0c2e5d9b1a4c7e` | The event id. The same across retries and resends. |
| `IPScope-Event-Type` | `database.updated` | The event type, so you can route before parsing the body. |
| `IPScope-Delivery-Id` | `e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40` | This delivery of the event to this endpoint. Shown in the delivery history. |
| `IPScope-Delivery-Attempt` | `1` | Which attempt this is, starting at `1` (and at `1` again after a resend). |
| `Content-Type` | `application/json` | The body is a JSON event envelope. |
| `User-Agent` | `ipscope-webhooks/1.0 (+https://ipscope.io)` | Identifies ipscope webhook requests. |

## `database.created`

The first release of a database is ready to download. `data` has the same shape as `database.updated`, with `release.previous_release_id` set to `null`.

```json database.created
{
  "id": "evt_1a7d3c9e5b2f4a8c1a7d3c9e5b2f4a8c",
  "object": "event",
  "type": "database.created",
  "api_version": "2026-11-04",
  "created_at": "2026-11-04T03:12:09.512Z",
  "data": {
    "database": {
      "id": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34",
      "name": "Fraud signals",
      "update_schedule": "daily"
    },
    "release": {
      "id": "rel_4c1e9a7b3f20_9d2b6e8a1c54",
      "previous_release_id": null,
      "built_at": "2026-11-04T03:10:44.000Z",
      "files": [
        {
          "format": "mmdb",
          "filename": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34_04112026.mmdb",
          "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
          "size_bytes": 81234567,
          "download_url": "https://api.ipscope.io/v1/mmdb/files/rel_4c1e9a7b3f20_9d2b6e8a1c54/mmdb"
        },
        {
          "format": "csv",
          "filename": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34_04112026.csv.gz",
          "sha256": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9",
          "size_bytes": 64120933,
          "download_url": "https://api.ipscope.io/v1/mmdb/files/rel_4c1e9a7b3f20_9d2b6e8a1c54/csv"
        },
        {
          "format": "parquet",
          "filename": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34_04112026.parquet",
          "sha256": "baa5a0964d3320fbc0c6a922140453c8513ea24ab8fd0577034804a967248096",
          "size_bytes": 52877410,
          "download_url": "https://api.ipscope.io/v1/mmdb/files/rel_4c1e9a7b3f20_9d2b6e8a1c54/parquet"
        }
      ]
    },
    "build": {
      "id": "dbc_5e8a2c9f1b7d4e3a6c0f"
    }
  }
}
```

## `database.updated`

A new release of the database is ready (for example after a refresh, a field upgrade or a rebuild). It is only sent when the release actually changed, so every `database.updated` is worth acting on.

**`data`**

- `database` (object): The database the event is about.
  - `id` (string): The database id, shown as **Database ID** in the dashboard (currently a UUID; treat it as an opaque string).
  - `name` (string | null): The name you gave the database, or `null` when it has none.
  - `update_schedule` (string | null): `daily`, `weekly`, `monthly`, or `null` when the database has no refresh schedule.
- `release` (object): The new release.
  - `id` (string): The release id (such as `rel_4c1e9a7b3f20_9d2b6e8a1c54`; releases shared by many databases start with `rel_mega_`). Treat it as an opaque string: use it in download URLs and to tell releases apart.
  - `previous_release_id` (string | null): The release this one replaces; `null` for `database.created`.
  - `built_at` (string | null): When the release was built (ISO 8601 UTC). Use it to order releases.
  - `files` (object[]): One entry per format the database includes (`mmdb`, `csv`, `parquet`); formats the database does not include are left out.
    - `format` (string): `mmdb`, `csv` or `parquet`.
    - `filename` (string): The file's download name: `<database id>_<DDMMYYYY>.<ext>`, with the day the release was built (UTC) and the extension `mmdb`, `csv.gz` or `parquet`.
    - `sha256` (string | null): Hex SHA-256 of the file. Check the download against it before using it.
    - `size_bytes` (integer | null): File size in bytes.
    - `download_url` (string): Where to download the file. Requires an API key with the `download` scope, exactly like [downloading](https://ipscope.io/docs/databases/downloading) from the API.
- `build` (object): The build that produced the release.
  - `id` (string): The build id (such as `dbc_5e8a2c9f1b7d4e3a6c0f`), an opaque string.

```json database.updated
{
  "id": "evt_8f0c2e5d9b1a4c7e8f0c2e5d9b1a4c7e",
  "object": "event",
  "type": "database.updated",
  "api_version": "2026-11-04",
  "created_at": "2026-11-04T03:12:09.512Z",
  "data": {
    "database": {
      "id": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34",
      "name": "Fraud signals",
      "update_schedule": "daily"
    },
    "release": {
      "id": "rel_4c1e9a7b3f20_9d2b6e8a1c54",
      "previous_release_id": "rel_7b3e0d9a52c1_e64f1a8c3d07",
      "built_at": "2026-11-04T03:10:44.000Z",
      "files": [
        {
          "format": "mmdb",
          "filename": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34_04112026.mmdb",
          "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
          "size_bytes": 81234567,
          "download_url": "https://api.ipscope.io/v1/mmdb/files/rel_4c1e9a7b3f20_9d2b6e8a1c54/mmdb"
        },
        {
          "format": "csv",
          "filename": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34_04112026.csv.gz",
          "sha256": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9",
          "size_bytes": 64120933,
          "download_url": "https://api.ipscope.io/v1/mmdb/files/rel_4c1e9a7b3f20_9d2b6e8a1c54/csv"
        },
        {
          "format": "parquet",
          "filename": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34_04112026.parquet",
          "sha256": "baa5a0964d3320fbc0c6a922140453c8513ea24ab8fd0577034804a967248096",
          "size_bytes": 52877410,
          "download_url": "https://api.ipscope.io/v1/mmdb/files/rel_4c1e9a7b3f20_9d2b6e8a1c54/parquet"
        }
      ]
    },
    "build": {
      "id": "dbc_5e8a2c9f1b7d4e3a6c0f"
    }
  }
}
```

> **Tip:** Downloading a file from `download_url` works like any other download: send `Authorization: Bearer <key>` with a `download`-scoped API key, then compare the file's SHA-256 with `sha256`. See [Downloading & checksums](https://ipscope.io/docs/databases/downloading) and [Automated zero-downtime updates](https://ipscope.io/docs/databases/updating).

## `database.build_failed`

A build did not complete. Nothing changes for you: the current release, if there is one, stays available for download. Use this event for alerting rather than for deployments.

**`data`**

- `database` (object): The database the event is about.
  - `id` (string): The database id, shown as **Database ID** in the dashboard (currently a UUID; treat it as an opaque string).
  - `name` (string | null): The name you gave the database, or `null` when it has none.
  - `update_schedule` (string | null): `daily`, `weekly`, `monthly`, or `null` when the database has no refresh schedule.
- `build` (object): The build that did not complete.
  - `id` (string): The build id, an opaque string.
  - `finished_at` (string | null): When the build stopped (ISO 8601 UTC).
- `current_release_id` (string | null): The release that stays available, or `null` when the database has no release yet.
- `message` (string): A human-readable explanation.

```json database.build_failed
{
  "id": "evt_4e9b2d7a1c6f3e8b4e9b2d7a1c6f3e8b",
  "object": "event",
  "type": "database.build_failed",
  "api_version": "2026-11-04",
  "created_at": "2026-11-04T03:12:09.512Z",
  "data": {
    "database": {
      "id": "3f6c1a52-8d4e-4b7a-9c21-5e0f7d9a1b34",
      "name": "Fraud signals",
      "update_schedule": "weekly"
    },
    "build": {
      "id": "dbc_5e8a2c9f1b7d4e3a6c0f",
      "finished_at": "2026-11-04T03:40:00.000Z"
    },
    "current_release_id": "rel_7b3e0d9a52c1_e64f1a8c3d07",
    "message": "This build did not complete. The current release stays available for download."
  }
}
```

## `webhook.test`

Sent to a single endpoint when you press **Send test event** in the dashboard or call the [test route](https://ipscope.io/docs/webhooks/api#send-a-test-event). It is signed like every other event, so it is a good way to check your verification code end to end.

**`data`**

- `endpoint_id` (string): The endpoint the test was sent to.
- `message` (string): Always `"Test event sent from your ipscope dashboard."`.

```json webhook.test
{
  "id": "evt_6c3a8f1e4d9b2c7a6c3a8f1e4d9b2c7a",
  "object": "event",
  "type": "webhook.test",
  "api_version": "2026-11-04",
  "created_at": "2026-11-04T03:12:09.512Z",
  "data": {
    "endpoint_id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
    "message": "Test event sent from your ipscope dashboard."
  }
}
```

## Ordering and duplicates

Events can arrive more than once and out of order. Keep the ids of events you have processed and skip repeats, and when two `database.updated` events for the same database arrive, act on the one with the newest `release.built_at`.
