# Jobs & webhooks

Poll results, stream job events, and manage webhook delivery.

All paths below are relative to `https://www.agentseo.dev/api/v1`. Send your key in `x-api-key`. Set `AGENTSEO_API_KEY` in your environment before running the examples. IDs and results are illustrative.

[Async result handling](https://www.agentseo.dev/docs/async-jobs) · [Errors and limits](https://www.agentseo.dev/docs/errors) · [OpenAPI contract](https://www.agentseo.dev/openapi.yaml)

## GET`/webhooks/endpoints`

List the webhook endpoints registered for your workspace.

GET /webhooks/endpoints example

```
curl https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: $AGENTSEO_API_KEY"
```

## POST`/webhooks/endpoints`

Create a signed webhook endpoint for async job delivery. The signing secret is returned once on create.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `url`Required | string | HTTPS endpoint that will receive webhook POSTs |
| `events` | array | Any of job.completed, job.failed, project.budget\_warning, or project.budget\_exceeded |

POST /webhooks/endpoints example

```
curl -X POST https://www.agentseo.dev/api/v1/webhooks/endpoints \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/agentseo","events":["job.completed","project.budget_warning","project.budget_exceeded"]}'
```

## PATCH`/webhooks/endpoints/{id}`

Update a webhook endpoint in place. Use this to rotate target URLs, event subscriptions, descriptions, or to pause delivery with is\_active=false.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `id`Required | string | Webhook endpoint ID |
| `url` | string | New HTTPS target URL |
| `description` | string | Optional human-readable label |
| `events` | array | Any of job.completed, job.failed, project.budget\_warning, or project.budget\_exceeded |
| `is_active` | boolean | Set false to pause deliveries without deleting the endpoint |

PATCH /webhooks/endpoints/{id} example

```
curl -X PATCH https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Primary production hook","is_active":false}'
```

## DELETE`/webhooks/endpoints/{id}`

Delete a webhook endpoint. This stops future deliveries to that target but does not remove historical delivery records.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `id`Required | string | Webhook endpoint ID |

DELETE /webhooks/endpoints/{id} example

```
curl -X DELETE https://www.agentseo.dev/api/v1/webhooks/endpoints/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: $AGENTSEO_API_KEY"
```

## GET`/webhooks/deliveries`

Inspect recent webhook delivery attempts, response codes, and failure reasons.

Query parameters · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `limit` | integer | Number of rows to return (default: 25, max: 100) |
| `status` | string | Filter by pending, delivered, or failed |
| `endpoint_id` | string | Filter to one webhook endpoint ID |
| `project_id` | string | Filter deliveries for one project, including budget alerts |
| `event_type` | string | Filter one event type such as project.budget\_warning or job.completed |

GET /webhooks/deliveries example

```
curl https://www.agentseo.dev/api/v1/webhooks/deliveries?limit=25&project_id=client-alpha&event_type=project.budget_exceeded \
  -H "x-api-key: $AGENTSEO_API_KEY"
```

## POST`/webhooks/deliveries/{id}/retry`

Retry a failed webhook delivery without re-running the underlying job.

Request fields · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `id`Required | string | Webhook delivery ID |

POST /webhooks/deliveries/{id}/retry example

```
curl -X POST https://www.agentseo.dev/api/v1/webhooks/deliveries/123e4567-e89b-12d3-a456-426614174000/retry \
  -H "x-api-key: $AGENTSEO_API_KEY"
```

## GET`/jobs/{id}`

Check the status of an async job. Returns public progress, attempts, result, error, and attribution context.

Query parameters · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `id`Required | string | Job ID from 202 response |

GET /jobs/{id} example

```
curl https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000 \
  -H "x-api-key: $AGENTSEO_API_KEY"
```

## GET`/jobs/{id}/events`

Open an SSE stream for live job updates. Emits events such as job.open, job.status, job.done, and job.failed.

Query parameters · required fields are labeled

| Name | Type | Description |
| --- | --- | --- |
| `id`Required | string | Job ID from a queued async request |

GET /jobs/{id}/events example

```
curl -N https://www.agentseo.dev/api/v1/jobs/123e4567-e89b-12d3-a456-426614174000/events \
  -H "x-api-key: $AGENTSEO_API_KEY" \
  -H "Accept: text/event-stream"
```

[← All endpoints](https://www.agentseo.dev/docs/api-reference)

---
Canonical HTML: https://www.agentseo.dev/docs/api-reference/system
Markdown: https://www.agentseo.dev/docs/api-reference/system/index.md