Webhooks
Markdown

Webhooks

Get a signed HTTPS request the moment a database release is ready, instead of polling for new files.

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.

EventSent 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 there is one, stays available.
webhook.testYou 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

  1. Step 1: Open API → Webhooks

    Sign in at https://dashboard.ipscope.io, open API → Webhooks and choose Add endpoint.

  2. Step 2: Enter the URL and choose events

    Enter a public https:// URL on your server, an optional description (such as Prod updater), and the events it should receive. Leave every event selected unless the endpoint only cares about some of them.

  3. 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 as IPSCOPE_WEBHOOK_SECRET) and use it to verify every request.

  4. Step 4: Send a test event

    Choose Send test event. Your endpoint receives a webhook.test event, 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
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:

Request to your endpoint
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

TopicBehavior
SuccessAny 2xx response within 10 seconds. The response body is ignored.
FailureAny other status, a timeout, a connection error or a TLS error. Redirects are not followed, so a 3xx is a failure.
RetriesFailed 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.
DuplicatesDelivery is at least once: the same event can arrive more than once. Deduplicate by the IPScope-Event-Id header (or the body's id).
OrderingNot guaranteed. Compare release.built_at or release ids rather than relying on arrival order.
Automatic disablingIf 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.
ResendingAny 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.
HistoryDeliveries, with status code, error and duration of the last attempt, are kept for 30 days.

# Retry schedule

AttemptSent
1As soon as the event happens
2About 1 minute after attempt 1 failed
3About 5 minutes later
4About 30 minutes later
5About 2 hours later
6About 5 hours later
7 – 10About 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 #fragment is removed.
  • The host must be a public internet name or address: single-label hosts (https://intranet/…), localhost and names ending in .local, .internal, .lan, .home, .corp or .localhost are 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 2xx within 10 seconds, even when the work the event starts takes longer.

# Best practices

  1. Verify the signature of every request on the raw body before trusting it (how).
  2. Respond fast, work later. Return 2xx as soon as the request is verified and recorded, then download the new release in a background job.
  3. Deduplicate by IPScope-Event-Id: retries and resends reuse the same event id.
  4. Verify the file after downloading: compare its SHA-256 with the sha256 in the event before swapping it in (zero-downtime updates).
  5. Do not rely on order. If two releases arrive close together, keep the one with the newest built_at.