Everything you can do under API → Webhooks in the dashboard is also available at https://api.ipscope.io/v1/webhooks. Authenticate with an API key in Authorization: Bearer <key> (the examples read it from $IPSCOPE_API_KEY). Endpoints belong to your account, not to the key.
| Status | Meaning |
|---|---|
400 | The request is invalid, for example a URL that is not public https://, an unknown event type, or the 10-endpoint limit is reached. |
401 | No API key, or an unknown, expired or revoked key. |
403 | The key lacks the lookup scope (API key "…" lacks required scope "lookup"). |
404 | No endpoint or delivery with that id on your account (an id that is not a UUID also gives 404). |
429 | Your account's per-second rate limit was exceeded; wait Retry-After seconds. |
503 | Webhooks are temporarily unavailable. Try again later. |
Error bodies are { "statusCode": 400, "message": "…", "error": "Bad Request" }. Secrets are returned in full only when you create an endpoint, fetch one by id, or rotate its secret. Lists show secret_hint instead.
# List endpoints
https://api.ipscope.io/v1/webhooksReturns your endpoints, the endpoint limit, and the event types you can subscribe to.
curl -sS "https://api.ipscope.io/v1/webhooks" \
-H "Authorization: Bearer $IPSCOPE_API_KEY"Your endpoints.
{
"endpoints": [
{
"id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
"url": "https://example.com/hooks/ipscope",
"description": "Prod updater",
"events": [
"database.updated"
],
"enabled": true,
"disabled_reason": null,
"secret_hint": "whsec_...vrog",
"last_success_at": "2026-11-04T03:12:09.512Z",
"last_failure_at": null,
"created_at": "2026-11-01T09:30:00.000Z",
"updated_at": "2026-11-01T09:30:00.000Z"
}
],
"max_endpoints": 10,
"event_types": [
"database.created",
"database.updated",
"database.build_failed"
]
}# Create an endpoint
https://api.ipscope.io/v1/webhookscurl -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"]}'The new endpoint, including its signing `secret`.
{
"id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
"url": "https://example.com/hooks/ipscope",
"description": "Prod updater",
"events": [
"database.updated"
],
"enabled": true,
"disabled_reason": null,
"secret": "whsec_8Yh1hqgCFzwujTnRk8AKyREOf2jPvsZ99OoqOrcvrog",
"secret_hint": "whsec_...vrog",
"last_success_at": "2026-11-04T03:12:09.512Z",
"last_failure_at": null,
"created_at": "2026-11-01T09:30:00.000Z",
"updated_at": "2026-11-01T09:30:00.000Z"
}# Get an endpoint
https://api.ipscope.io/v1/webhooks/{id}curl -sS "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24" \
-H "Authorization: Bearer $IPSCOPE_API_KEY"The endpoint, including its signing `secret`.
{
"id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
"url": "https://example.com/hooks/ipscope",
"description": "Prod updater",
"events": [
"database.updated"
],
"enabled": true,
"disabled_reason": null,
"secret": "whsec_8Yh1hqgCFzwujTnRk8AKyREOf2jPvsZ99OoqOrcvrog",
"secret_hint": "whsec_...vrog",
"last_success_at": "2026-11-04T03:12:09.512Z",
"last_failure_at": null,
"created_at": "2026-11-01T09:30:00.000Z",
"updated_at": "2026-11-01T09:30:00.000Z"
}# Update an endpoint
https://api.ipscope.io/v1/webhooks/{id}Send only the fields you want to change. Set enabled to true to turn an endpoint back on after it was disabled for repeated failures (this also clears disabled_reason and its failure count). Setting it to false stops deliveries (disabled_reason becomes Disabled by you).
curl -sS -X PATCH "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24" \
-H "Authorization: Bearer $IPSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled":true}'The updated endpoint.
{
"id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
"url": "https://example.com/hooks/ipscope",
"description": "Prod updater",
"events": [
"database.updated"
],
"enabled": true,
"disabled_reason": null,
"secret_hint": "whsec_...vrog",
"last_success_at": "2026-11-04T03:12:09.512Z",
"last_failure_at": null,
"created_at": "2026-11-01T09:30:00.000Z",
"updated_at": "2026-11-01T09:30:00.000Z"
}# Delete an endpoint
https://api.ipscope.io/v1/webhooks/{id}Stops all deliveries to the endpoint and removes it.
curl -sS -X DELETE "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24" \
-H "Authorization: Bearer $IPSCOPE_API_KEY"The endpoint was deleted.
# Rotate the signing secret
https://api.ipscope.io/v1/webhooks/{id}/rotate-secretReplaces the endpoint's signing secret. The old secret stops working immediately: deploy the new one to your receiver right away.
curl -sS -X POST "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24/rotate-secret" \
-H "Authorization: Bearer $IPSCOPE_API_KEY"The endpoint with its new `secret`.
{
"id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
"url": "https://example.com/hooks/ipscope",
"description": "Prod updater",
"events": [
"database.updated"
],
"enabled": true,
"disabled_reason": null,
"secret": "whsec_8Yh1hqgCFzwujTnRk8AKyREOf2jPvsZ99OoqOrcvrog",
"secret_hint": "whsec_...vrog",
"last_success_at": "2026-11-04T03:12:09.512Z",
"last_failure_at": null,
"created_at": "2026-11-01T09:30:00.000Z",
"updated_at": "2026-11-01T09:30:00.000Z"
}# Send a test event
https://api.ipscope.io/v1/webhooks/{id}/testQueues a signed webhook.test event to this endpoint only. The endpoint must be enabled. Follow the result in the endpoint's deliveries.
curl -sS -X POST "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24/test" \
-H "Authorization: Bearer $IPSCOPE_API_KEY"The test event is queued for delivery.
{
"event_id": "evt_6c3a8f1e4d9b2c7a6c3a8f1e4d9b2c7a",
"delivery_id": "e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40",
"status": "pending"
}# List deliveries
https://api.ipscope.io/v1/webhooks/{id}/deliverieshttps://api.ipscope.io/v1/webhooks/deliveriesThe first route lists one endpoint's deliveries, the second every endpoint's. limit sets how many to return (default 50, at most 100). Deliveries are kept for 30 days. The first route does not check that the endpoint exists: an id that is a UUID but not one of your endpoints returns 200 with {"deliveries": []}; an id that is not a UUID returns 404.
curl -sS "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24/deliveries?limit=50" \
-H "Authorization: Bearer $IPSCOPE_API_KEY"The most recent deliveries, newest first.
{
"deliveries": [
{
"id": "f1c9a7e5-3b2d-4f80-9e6c-4b2a0f8d6e51",
"event_id": "evt_4e9b2d7a1c6f3e8b4e9b2d7a1c6f3e8b",
"event_type": "database.build_failed",
"endpoint_id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
"status": "failed",
"attempts": 2,
"next_attempt_at": "2026-11-04T03:46:12.000Z",
"last_status_code": 503,
"last_error": "HTTP 503",
"last_duration_ms": 94,
"created_at": "2026-11-04T03:40:01.204Z",
"delivered_at": null
},
{
"id": "e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40",
"event_id": "evt_8f0c2e5d9b1a4c7e8f0c2e5d9b1a4c7e",
"event_type": "database.updated",
"endpoint_id": "a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24",
"status": "succeeded",
"attempts": 1,
"next_attempt_at": null,
"last_status_code": 204,
"last_error": null,
"last_duration_ms": 182,
"created_at": "2026-11-04T03:12:09.512Z",
"delivered_at": "2026-11-04T03:12:09.731Z"
}
]
}# Resend a delivery
https://api.ipscope.io/v1/webhooks/deliveries/{id}/resendSends any delivery again (succeeded, failed or abandoned), for example after fixing your receiver, rotating a secret or re-enabling the endpoint. The delivery keeps its delivery id, event id and body, and starts over with a fresh set of 10 attempts: attempts goes back to 0 and IPScope-Delivery-Attempt starts at 1 again. The endpoint must be enabled, and a delivery cannot be resent while an attempt is in progress. Deduplicate by event id on your side, as with any retry.
curl -sS -X POST "https://api.ipscope.io/v1/webhooks/deliveries/e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40/resend" \
-H "Authorization: Bearer $IPSCOPE_API_KEY"The delivery is queued again.
{
"delivery_id": "e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40",
"status": "pending"
}