Webhooks
Markdown

Managing endpoints (API)

Create, update, test and delete webhook endpoints and inspect or resend deliveries with the REST API.

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.

StatusMeaning
400The request is invalid, for example a URL that is not public https://, an unknown event type, or the 10-endpoint limit is reached.
401No API key, or an unknown, expired or revoked key.
403The key lacks the lookup scope (API key "…" lacks required scope "lookup").
404No endpoint or delivery with that id on your account (an id that is not a UUID also gives 404).
429Your account's per-second rate limit was exceeded; wait Retry-After seconds.
503Webhooks 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

GEThttps://api.ipscope.io/v1/webhooksscope: lookup API key

Returns your endpoints, the endpoint limit, and the event types you can subscribe to.

curl
curl -sS "https://api.ipscope.io/v1/webhooks" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
Responses
application/json

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

POSThttps://api.ipscope.io/v1/webhooksscope: lookup · 201 Created API key
Request bodyCreateWebhookEndpointapplication/json
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"]}'
Responses
application/json

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

GEThttps://api.ipscope.io/v1/webhooks/{id}scope: lookup API key
curl
curl -sS "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
Responses
application/json

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

PATCHhttps://api.ipscope.io/v1/webhooks/{id}scope: lookup API key

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).

Request bodyUpdateWebhookEndpointapplication/json
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}'
Responses
application/json

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

DELETEhttps://api.ipscope.io/v1/webhooks/{id}scope: lookup · 204 No Content API key

Stops all deliveries to the endpoint and removes it.

curl
curl -sS -X DELETE "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
Responses
application/json

The endpoint was deleted.

# Rotate the signing secret

POSThttps://api.ipscope.io/v1/webhooks/{id}/rotate-secretscope: lookup API key

Replaces the endpoint's signing secret. The old secret stops working immediately: deploy the new one to your receiver right away.

curl
curl -sS -X POST "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24/rotate-secret" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
Responses
application/json

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

POSThttps://api.ipscope.io/v1/webhooks/{id}/testscope: lookup · 202 Accepted API key

Queues a signed webhook.test event to this endpoint only. The endpoint must be enabled. Follow the result in the endpoint's deliveries.

curl
curl -sS -X POST "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24/test" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
Responses
application/json

The test event is queued for delivery.

{
  "event_id": "evt_6c3a8f1e4d9b2c7a6c3a8f1e4d9b2c7a",
  "delivery_id": "e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40",
  "status": "pending"
}

# List deliveries

GEThttps://api.ipscope.io/v1/webhooks/{id}/deliveriesscope: lookup API key
GEThttps://api.ipscope.io/v1/webhooks/deliveriesscope: lookup API key

The 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"
Responses
application/json

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

POSThttps://api.ipscope.io/v1/webhooks/deliveries/{id}/resendscope: lookup · 202 Accepted API key

Sends 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
curl -sS -X POST "https://api.ipscope.io/v1/webhooks/deliveries/e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40/resend" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
Responses
application/json

The delivery is queued again.

{
  "delivery_id": "e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40",
  "status": "pending"
}