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. |
# The event envelope
idstringrequiredUnique event id, starting withevt_. Equal to theIPScope-Event-Idheader and the same on every retry: use it to deduplicate.objectstringrequiredAlways"event".typestringrequiredThe event type, such asdatabase.updated. Equal to theIPScope-Event-Typeheader.api_versionstringrequiredThe payload version, currently"2026-11-04".created_atstringrequiredWhen the event happened, as an ISO 8601 UTC timestamp.dataobjectrequiredThe 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). |
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.
{
"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`
databaseobjectThe database the event is about.3 fields
idstringThe database id, shown as Database ID in the dashboard (currently a UUID; treat it as an opaque string).namestring | nullThe name you gave the database, ornullwhen it has none.update_schedulestring | nulldaily,weekly,monthly, ornullwhen the database has no refresh schedule.
releaseobjectThe new release.4 fields
idstringThe release id (such asrel_4c1e9a7b3f20_9d2b6e8a1c54; releases shared by many databases start withrel_mega_). Treat it as an opaque string: use it in download URLs and to tell releases apart.previous_release_idstring | nullThe release this one replaces;nullfordatabase.created.built_atstring | nullWhen 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
formatstringmmdb,csvorparquet.filenamestringThe file's download name:<database id>_<DDMMYYYY>.<ext>, with the day the release was built (UTC) and the extensionmmdb,csv.gzorparquet.sha256string | nullHex SHA-256 of the file. Check the download against it before using it.size_bytesinteger | nullFile size in bytes.download_urlstringWhere to download the file. Requires an API key with thedownloadscope, exactly like downloading from the API.
buildobjectThe build that produced the release.1 field
idstringThe build id (such asdbc_5e8a2c9f1b7d4e3a6c0f), an opaque string.
{
"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`
databaseobjectThe database the event is about.3 fields
idstringThe database id, shown as Database ID in the dashboard (currently a UUID; treat it as an opaque string).namestring | nullThe name you gave the database, ornullwhen it has none.update_schedulestring | nulldaily,weekly,monthly, ornullwhen the database has no refresh schedule.
buildobjectThe build that did not complete.2 fields
idstringThe build id, an opaque string.finished_atstring | nullWhen the build stopped (ISO 8601 UTC).
current_release_idstring | nullThe release that stays available, ornullwhen the database has no release yet.messagestringA human-readable explanation.
{
"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_idstringThe endpoint the test was sent to.messagestringAlways"Test event sent from your ipscope dashboard.".
{
"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.