Webhooks
Markdown

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.

TypeSent when
database.createdThe first release of a database is ready to download.
database.updatedA 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_failedA build did not complete. The current release, if any, stays available.
webhook.testA test event sent to one endpoint from the dashboard's Send test event or the test route.

# The event envelope

  • idstringrequired
    Unique event id, starting with evt_. Equal to the IPScope-Event-Id header and the same on every retry: use it to deduplicate.
  • objectstringrequired
    Always "event".
  • typestringrequired
    The event type, such as database.updated. Equal to the IPScope-Event-Type header.
  • api_versionstringrequired
    The payload version, currently "2026-11-04".
  • created_atstringrequired
    When the event happened, as an ISO 8601 UTC timestamp.
  • dataobjectrequired
    The event's details, described below for each type.

# Request headers

HeaderExampleMeaning
IPScope-Signaturet=1793761929,v1=d48dd8…Timestamp and HMAC-SHA256 signature of the request (verifying).
IPScope-Event-Idevt_8f0c2e5d9b1a4c7e8f0c2e5d9b1a4c7eThe event id. The same across retries and resends.
IPScope-Event-Typedatabase.updatedThe event type, so you can route before parsing the body.
IPScope-Delivery-Ide8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40This delivery of the event to this endpoint. Shown in the delivery history.
IPScope-Delivery-Attempt1Which attempt this is, starting at 1 (and at 1 again after a resend).
Content-Typeapplication/jsonThe body is a JSON event envelope.
User-Agentipscope-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.

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`

  • databaseobject
    The database the event is about.
    3 fields
    • idstring
      The database id, shown as Database ID in the dashboard (currently a UUID; treat it as an opaque string).
    • namestring | null
      The name you gave the database, or null when it has none.
    • update_schedulestring | null
      daily, weekly, monthly, or null when the database has no refresh schedule.
  • releaseobject
    The new release.
    4 fields
    • idstring
      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_idstring | null
      The release this one replaces; null for database.created.
    • built_atstring | null
      When the release was built (ISO 8601 UTC). Use it to order releases.
    • filesobject[]
      One entry per format the database includes (mmdb, csv, parquet); formats the database does not include are left out.
      5 fields
      • formatstring
        mmdb, csv or parquet.
      • filenamestring
        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.
      • sha256string | null
        Hex SHA-256 of the file. Check the download against it before using it.
      • size_bytesinteger | null
        File size in bytes.
      • download_urlstring
        Where to download the file. Requires an API key with the download scope, exactly like downloading from the API.
  • buildobject
    The build that produced the release.
    1 field
    • idstring
      The build id (such as dbc_5e8a2c9f1b7d4e3a6c0f), an opaque string.
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"
    }
  }
}

# `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`

  • databaseobject
    The database the event is about.
    3 fields
    • idstring
      The database id, shown as Database ID in the dashboard (currently a UUID; treat it as an opaque string).
    • namestring | null
      The name you gave the database, or null when it has none.
    • update_schedulestring | null
      daily, weekly, monthly, or null when the database has no refresh schedule.
  • buildobject
    The build that did not complete.
    2 fields
    • idstring
      The build id, an opaque string.
    • finished_atstring | null
      When the build stopped (ISO 8601 UTC).
  • current_release_idstring | null
    The release that stays available, or null when the database has no release yet.
  • messagestring
    A human-readable explanation.
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. It is signed like every other event, so it is a good way to check your verification code end to end.

`data`

  • endpoint_idstring
    The endpoint the test was sent to.
  • messagestring
    Always "Test event sent from your ipscope dashboard.".
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.