Webhooks let ipscope tell your systems when something happens to your databases: the first release of a new database is ready, a new release replaces the current one, or a build did not complete. Point a webhook at your deployment pipeline and it can download and roll out the new file within minutes of it being built, with no timer and no polling.
A webhook is a URL on your server. When an event happens, ipscope sends it a POST request with a JSON body describing the event, signed with a secret only you and ipscope know, much like webhooks from other platforms you may already use.
| Event | 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 there is one, stays available. |
webhook.test | You pressed Send test event in the dashboard or called the test route. |
Full payloads for each event are on Event types & payloads.
# Add an endpoint in the dashboard
Step 1: Open API → Webhooks
Sign in at https://dashboard.ipscope.io, open API → Webhooks and choose Add endpoint.
Step 2: Enter the URL and choose events
Enter a public
https://URL on your server, an optional description (such asProd updater), and the events it should receive. Leave every event selected unless the endpoint only cares about some of them.Step 3: Copy the signing secret
Each endpoint has its own signing secret:
whsec_followed by 43 base64url characters. Store it with your other secrets (for example asIPSCOPE_WEBHOOK_SECRET) and use it to verify every request.Step 4: Send a test event
Choose Send test event. Your endpoint receives a
webhook.testevent, and the delivery shows up in the endpoint's history with the status code your server answered.
# Add an endpoint with the API
The same endpoints can be managed with an API key, which suits infrastructure-as-code. The response includes the secret; see Managing endpoints for every route.
curl -sS -X POST "https://api.ipscope.io/v1/webhooks" \
-H "Authorization: Bearer $IPSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hooks/ipscope","description":"Prod updater","events":["database.updated"]}'# What a delivery looks like
Every delivery is a POST with Content-Type: application/json and User-Agent: ipscope-webhooks/1.0 (+https://ipscope.io). The IPScope-* headers identify the event and the attempt:
POST /hooks/ipscope HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: ipscope-webhooks/1.0 (+https://ipscope.io)
IPScope-Signature: t=1793761929,v1=d48dd86bdda97d482f2cc4a81cc14e88692654757a8c027f39c1d95a52ad8776
IPScope-Event-Id: evt_8f0c2e5d9b1a4c7e8f0c2e5d9b1a4c7e
IPScope-Event-Type: database.updated
IPScope-Delivery-Id: e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40
IPScope-Delivery-Attempt: 1
{"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"}}}The body is compact JSON. The order of its keys is not specified and can differ from the examples on these pages, so parse it as JSON and verify the signature over the bytes exactly as received. The signature above is real: it verifies for this body with the sample secret whsec_8Yh1hqgCFzwujTnRk8AKyREOf2jPvsZ99OoqOrcvrog at that timestamp.
# Delivery guarantees
| Topic | Behavior |
|---|---|
| Success | Any 2xx response within 10 seconds. The response body is ignored. |
| Failure | Any other status, a timeout, a connection error or a TLS error. Redirects are not followed, so a 3xx is a failure. |
| Retries | Failed deliveries are retried with back-off, up to 10 attempts over about 2 days (schedule below). Every attempt carries the same event id and body; the signature timestamp is fresh on each attempt. |
| Duplicates | Delivery is at least once: the same event can arrive more than once. Deduplicate by the IPScope-Event-Id header (or the body's id). |
| Ordering | Not guaranteed. Compare release.built_at or release ids rather than relying on arrival order. |
| Automatic disabling | If the last 5 deliveries to an endpoint all failed, each after all of its retries, the endpoint is disabled (webhook.test deliveries count too). While an endpoint is disabled, its events are lost: no deliveries are created for new events, retries that were still pending are abandoned (Endpoint disabled), and nothing is replayed when you turn it back on. Re-enable it in the dashboard or with PATCH /v1/webhooks/{id} and {"enabled": true}, then resend any delivery you still need. |
| Resending | Any delivery (succeeded, failed or abandoned) can be sent again from the dashboard or with POST /v1/webhooks/deliveries/{id}/resend. It keeps its delivery id and event id and starts a fresh set of 10 attempts. |
| History | Deliveries, with status code, error and duration of the last attempt, are kept for 30 days. |
# Retry schedule
| Attempt | Sent |
|---|---|
| 1 | As soon as the event happens |
| 2 | About 1 minute after attempt 1 failed |
| 3 | About 5 minutes later |
| 4 | About 30 minutes later |
| 5 | About 2 hours later |
| 6 | About 5 hours later |
| 7 – 10 | About every 10 hours |
Each wait varies by up to 10% either way, so endpoints that failed together do not retry together. The IPScope-Delivery-Attempt header says which attempt a request is (1 for the first). webhook.test deliveries are retried on the same schedule.
# Endpoint requirements
- A public
https://URL of up to 2,048 characters. URLs with credentials in them (https://user:pass@…) are rejected, and any#fragmentis removed. - The host must be a public internet name or address: single-label hosts (
https://intranet/…),localhostand names ending in.local,.internal,.lan,.home,.corpor.localhostare rejected, as are private, loopback, link-local, documentation and other reserved IP addresses. The name is resolved again on every delivery, and a delivery to a name that now resolves to a private or reserved address fails. - Up to 10 endpoints per account. Each endpoint can subscribe to any subset of the event types.
- Answer with a
2xxwithin 10 seconds, even when the work the event starts takes longer.
# Best practices
- Verify the signature of every request on the raw body before trusting it (how).
- Respond fast, work later. Return
2xxas soon as the request is verified and recorded, then download the new release in a background job. - Deduplicate by
IPScope-Event-Id: retries and resends reuse the same event id. - Verify the file after downloading: compare its SHA-256 with the
sha256in the event before swapping it in (zero-downtime updates). - Do not rely on order. If two releases arrive close together, keep the one with the newest
built_at.