# 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](https://dashboard.ipscope.io) 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

```http
GET https://api.ipscope.io/v1/webhooks
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup

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

```bash curl
curl -sS "https://api.ipscope.io/v1/webhooks" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
```

### 200 `WebhookEndpointList`: Your endpoints.

- `endpoints` (WebhookEndpoint[], required): Every endpoint on your account, without `secret`.
  - `id` (string, required): The endpoint id.
  - `url` (string, required): Where events are sent. A public `https://` URL.
  - `description` (string, optional, nullable): Your label for the endpoint.
  - `events` (string[], required): The event types this endpoint receives.
  - `enabled` (boolean, required): Whether events are delivered to the endpoint.
  - `disabled_reason` (string, optional, nullable): Why the endpoint is disabled: `Disabled automatically after repeated failed deliveries` or `Disabled by you`. `null` while enabled.
  - `secret_hint` (string, required): The last characters of the secret, to tell secrets apart.
  - `last_success_at` (string, optional, nullable): When a delivery last succeeded.
  - `last_failure_at` (string, optional, nullable): When a delivery attempt last failed.
  - `created_at` (string, required): When the endpoint was added.
  - `updated_at` (string, required): When the endpoint was last changed.
- `max_endpoints` (integer, required): How many endpoints an account can have.
- `event_types` (string[], required): Event types an endpoint can subscribe to.

```json 200 WebhookEndpointList
{
  "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

```http
POST https://api.ipscope.io/v1/webhooks
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup · 201 Created

**Request body** (CreateWebhookEndpoint)

- `url` (string, required): A public `https://` URL. Private and internal addresses and URLs with credentials are rejected.
- `description` (string, optional, nullable): Your label for the endpoint, up to 200 characters.
- `events` (string[], optional): Event types to receive. Leave it out to receive every type; when given, it must list at least one.

```json Example
{
  "url": "https://example.com/hooks/ipscope",
  "description": "Prod updater",
  "events": [
    "database.updated"
  ]
}
```

```bash 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"]}'
```

### 201 `WebhookEndpoint`: The new endpoint, including its signing `secret`.

- `id` (string, required): The endpoint id.
- `url` (string, required): Where events are sent. A public `https://` URL.
- `description` (string, optional, nullable): Your label for the endpoint.
- `events` (string[], required): The event types this endpoint receives.
- `enabled` (boolean, required): Whether events are delivered to the endpoint.
- `disabled_reason` (string, optional, nullable): Why the endpoint is disabled: `Disabled automatically after repeated failed deliveries` or `Disabled by you`. `null` while enabled.
- `secret` (string, required): The signing secret. Returned only when the endpoint is created, fetched by id, or its secret is rotated.
- `secret_hint` (string, required): The last characters of the secret, to tell secrets apart.
- `last_success_at` (string, optional, nullable): When a delivery last succeeded.
- `last_failure_at` (string, optional, nullable): When a delivery attempt last failed.
- `created_at` (string, required): When the endpoint was added.
- `updated_at` (string, required): When the endpoint was last changed.

```json 201 WebhookEndpoint
{
  "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"
}
```

### 400 `ApiError`: Invalid URL or events, or the endpoint limit is reached.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 400 ApiError
{
  "statusCode": 400,
  "message": "Choose at least one event.",
  "error": "Bad Request"
}
```

## Get an endpoint

```http
GET https://api.ipscope.io/v1/webhooks/{id}
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup

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

### 200 `WebhookEndpoint`: The endpoint, including its signing `secret`.

- `id` (string, required): The endpoint id.
- `url` (string, required): Where events are sent. A public `https://` URL.
- `description` (string, optional, nullable): Your label for the endpoint.
- `events` (string[], required): The event types this endpoint receives.
- `enabled` (boolean, required): Whether events are delivered to the endpoint.
- `disabled_reason` (string, optional, nullable): Why the endpoint is disabled: `Disabled automatically after repeated failed deliveries` or `Disabled by you`. `null` while enabled.
- `secret` (string, required): The signing secret. Returned only when the endpoint is created, fetched by id, or its secret is rotated.
- `secret_hint` (string, required): The last characters of the secret, to tell secrets apart.
- `last_success_at` (string, optional, nullable): When a delivery last succeeded.
- `last_failure_at` (string, optional, nullable): When a delivery attempt last failed.
- `created_at` (string, required): When the endpoint was added.
- `updated_at` (string, required): When the endpoint was last changed.

```json 200 WebhookEndpoint
{
  "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"
}
```

### 404 `ApiError`: No endpoint with this id on your account.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 404 ApiError
{
  "statusCode": 404,
  "message": "Webhook endpoint not found",
  "error": "Not Found"
}
```

## Update an endpoint

```http
PATCH https://api.ipscope.io/v1/webhooks/{id}
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup

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

> **Events are lost while disabled:** Disabling is not a pause. While an endpoint is disabled, events are not queued for it: no deliveries are created for new events, retries that were still pending are abandoned with `Endpoint disabled`, and nothing is replayed when you set `enabled` back to `true`. After re-enabling, resend any delivery you still need, or check for new releases another way.

**Request body** (UpdateWebhookEndpoint)

- `url` (string, optional): A new public `https://` URL.
- `description` (string, optional, nullable): A new label, up to 200 characters.
- `events` (string[], optional): The event types to receive (at least one).
- `enabled` (boolean, optional): Whether events are delivered to the endpoint.

```json Example
{
  "enabled": true
}
```

```bash Re-enable
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}'
```

```bash Change events
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 '{"events":["database.updated","database.build_failed"]}'
```

### 200 `WebhookEndpoint`: The updated endpoint.

- `id` (string, required): The endpoint id.
- `url` (string, required): Where events are sent. A public `https://` URL.
- `description` (string, optional, nullable): Your label for the endpoint.
- `events` (string[], required): The event types this endpoint receives.
- `enabled` (boolean, required): Whether events are delivered to the endpoint.
- `disabled_reason` (string, optional, nullable): Why the endpoint is disabled: `Disabled automatically after repeated failed deliveries` or `Disabled by you`. `null` while enabled.
- `secret_hint` (string, required): The last characters of the secret, to tell secrets apart.
- `last_success_at` (string, optional, nullable): When a delivery last succeeded.
- `last_failure_at` (string, optional, nullable): When a delivery attempt last failed.
- `created_at` (string, required): When the endpoint was added.
- `updated_at` (string, required): When the endpoint was last changed.

```json 200 WebhookEndpoint
{
  "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"
}
```

### 400 `ApiError`: An invalid field.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 400 ApiError
{
  "statusCode": 400,
  "message": "Unknown event \"database.deleted\".",
  "error": "Bad Request"
}
```

### 404 `ApiError`: No endpoint with this id on your account.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 404 ApiError
{
  "statusCode": 404,
  "message": "Webhook endpoint not found",
  "error": "Not Found"
}
```

## Delete an endpoint

```http
DELETE https://api.ipscope.io/v1/webhooks/{id}
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup · 204 No Content

Stops all deliveries to the endpoint and removes it.

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

### 204 `No Content`: The endpoint was deleted.

### 404 `ApiError`: No endpoint with this id on your account.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 404 ApiError
{
  "statusCode": 404,
  "message": "Webhook endpoint not found",
  "error": "Not Found"
}
```

## Rotate the signing secret

```http
POST https://api.ipscope.io/v1/webhooks/{id}/rotate-secret
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup

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

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

### 200 `WebhookEndpoint`: The endpoint with its new `secret`.

- `id` (string, required): The endpoint id.
- `url` (string, required): Where events are sent. A public `https://` URL.
- `description` (string, optional, nullable): Your label for the endpoint.
- `events` (string[], required): The event types this endpoint receives.
- `enabled` (boolean, required): Whether events are delivered to the endpoint.
- `disabled_reason` (string, optional, nullable): Why the endpoint is disabled: `Disabled automatically after repeated failed deliveries` or `Disabled by you`. `null` while enabled.
- `secret` (string, required): The signing secret. Returned only when the endpoint is created, fetched by id, or its secret is rotated.
- `secret_hint` (string, required): The last characters of the secret, to tell secrets apart.
- `last_success_at` (string, optional, nullable): When a delivery last succeeded.
- `last_failure_at` (string, optional, nullable): When a delivery attempt last failed.
- `created_at` (string, required): When the endpoint was added.
- `updated_at` (string, required): When the endpoint was last changed.

```json 200 WebhookEndpoint
{
  "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"
}
```

### 404 `ApiError`: No endpoint with this id on your account.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 404 ApiError
{
  "statusCode": 404,
  "message": "Webhook endpoint not found",
  "error": "Not Found"
}
```

## Send a test event

```http
POST https://api.ipscope.io/v1/webhooks/{id}/test
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup · 202 Accepted

Queues a signed [`webhook.test`](https://ipscope.io/docs/webhooks/events#webhook-test) event to this endpoint only. The endpoint must be enabled. Follow the result in the endpoint's deliveries.

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

### 202 `WebhookTestQueued`: The test event is queued for delivery.

- `event_id` (string, required): The test event's id.
- `delivery_id` (string, required): The delivery to watch.
- `status` (string, required): Always `pending` at this point.

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

### 400 `ApiError`: The endpoint is disabled.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 400 ApiError
{
  "statusCode": 400,
  "message": "Enable the endpoint before sending a test event.",
  "error": "Bad Request"
}
```

### 404 `ApiError`: No endpoint with this id on your account.

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 404 ApiError
{
  "statusCode": 404,
  "message": "Webhook endpoint not found",
  "error": "Not Found"
}
```

## List deliveries

```http
GET https://api.ipscope.io/v1/webhooks/{id}/deliveries
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup

```http
GET https://api.ipscope.io/v1/webhooks/deliveries
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup

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

```bash One endpoint
curl -sS "https://api.ipscope.io/v1/webhooks/a1d3f5b7-2c4e-4a6b-8d0f-1e3a5c7b9d24/deliveries?limit=50" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
```

```bash All endpoints
curl -sS "https://api.ipscope.io/v1/webhooks/deliveries?limit=50" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
```

### 200 `WebhookDeliveryList`: The most recent deliveries, newest first.

- `deliveries` (WebhookDelivery[], required): Deliveries from the last 30 days.
  - `id` (string, required): The delivery id, also sent as `IPScope-Delivery-Id`.
  - `event_id` (string, required): The event delivered (`evt_…`).
  - `event_type` (string, required): The event type.
  - `endpoint_id` (string, required): The endpoint it was sent to.
  - `status` (string, required): `pending`: waiting for its first or next attempt. `sending`: an attempt is in progress. `succeeded`: your endpoint answered `2xx`. `failed`: the last attempt failed and another is scheduled at `next_attempt_at`. `abandoned`: every attempt failed, or the endpoint was disabled before the delivery finished (`last_error` is then `Endpoint disabled` unless an attempt had already failed); resend it to try again.
  - `attempts` (integer, required): Attempts made so far (up to 10). A resend sets it back to `0`.
  - `next_attempt_at` (string, optional, nullable): When the next attempt is due, if one is scheduled.
  - `last_status_code` (integer, optional, nullable): HTTP status your endpoint returned on the last attempt; `null` when it did not answer.
  - `last_error` (string, optional, nullable): Why the last attempt failed (for example a timeout or `HTTP 500`).
  - `last_duration_ms` (integer, optional, nullable): How long the last attempt took, in milliseconds.
  - `created_at` (string, required): When the delivery was created.
  - `delivered_at` (string, optional, nullable): When it succeeded.

```json 200 WebhookDeliveryList
{
  "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

```http
POST https://api.ipscope.io/v1/webhooks/deliveries/{id}/resend
```

Authentication: API key (`X-API-Key` header or `Authorization: Bearer`). Plan: scope: lookup · 202 Accepted

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.

```bash curl
curl -sS -X POST "https://api.ipscope.io/v1/webhooks/deliveries/e8b6d4c2-a0f9-4e7d-8c5b-3a1f9e7d5c40/resend" \
  -H "Authorization: Bearer $IPSCOPE_API_KEY"
```

### 202 `WebhookResendQueued`: The delivery is queued again.

- `delivery_id` (string, required): The delivery being resent.
- `status` (string, required): Always `pending` at this point.

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

### 404 `ApiError`: No delivery with this id on your account, its endpoint is disabled, or an attempt is in progress right now (try again shortly).

- `statusCode` (integer, required): HTTP status code.
- `message` (string, required): What went wrong, in plain words.
- `error` (string, optional): The name of the HTTP status.

```json 404 ApiError
{
  "statusCode": 404,
  "message": "Delivery not found, or its endpoint is disabled",
  "error": "Not Found"
}
```
