Webhooks API

Register and manage webhook endpoints to receive real-time event notifications.

AgentVista delivers real-time event notifications to your registered HTTPS endpoints. Each delivery is signed with an HMAC-SHA256 signature using a secret key so you can verify that requests originate from AgentVista.

Webhook endpoints are scoped to an organization. Managing endpoints requires org admin permissions. Reading delivery history requires org member permissions.

The signing secret is returned exactly once when you create an endpoint or rotate the secret. Copy it immediately — it is never shown again. Store it securely and use it to verify incoming request signatures.

---

Create a webhook endpoint

cURL

curl -X POST https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/agentvista",
    "name": "Production alerting",
    "event_types": ["alert.fired", "trace.failed"]
  }'

POST /org/{org_slug}/webhooks/endpoints

Registers a new webhook endpoint for the organization. The signing secret (secret) is returned in this response only. Requires org admin role.

Path parameters

org_slug · string · required

Your organization slug.

Request body

url · string · required

HTTPS URL that AgentVista will POST event payloads to. Must start with https:// — HTTP URLs are rejected.

name · string

Human-readable label for this endpoint.

event_types · string[] · required

List of event types to deliver to this endpoint. Must contain at least one entry (e.g. ["alert.fired"]).

Response — 201

id · string

UUID of the new endpoint.

url · string

The registered HTTPS URL.

name · string

Endpoint label.

event_types · string[]

Subscribed event types.

is_active · boolean

Always true on creation.

created_at · string

ISO 8601 creation timestamp.

secret · string

Raw HMAC-SHA256 signing key. This is the only time this value is returned. Store it and use it to verify the X-AgentVista-Signature header on incoming deliveries.

Example response

{
  "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",
  "url": "https://hooks.example.com/agentvista",
  "name": "Production alerting",
  "event_types": ["alert.fired", "trace.failed"],
  "is_active": true,
  "created_at": "2024-01-15T10:00:00Z",
  "secret": "whsec_..."
}

---

List webhook endpoints

cURL

curl https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /org/{org_slug}/webhooks/endpoints

Lists all webhook endpoints for the organization, ordered newest-first. Secrets are never included in list responses.

Path parameters

org_slug · string · required

Your organization slug.

Response — 200

An array of endpoint objects. Each object has the following fields (no secret field):

id · string

Endpoint UUID.

url · string

Registered HTTPS URL.

name · string

Endpoint label.

event_types · string[]

Subscribed event types.

is_active · boolean

Whether the endpoint receives deliveries.

consecutive_failures · number

Number of consecutive failed delivery attempts. If this reaches the circuit-breaker threshold, the endpoint is automatically paused.

created_at · string

ISO 8601 creation timestamp.

---

Update a webhook endpoint

Pause endpoint

curl -X PATCH https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

PATCH /org/{org_slug}/webhooks/endpoints/{endpoint_id}

Updates one or more fields on a webhook endpoint. All request body fields are optional. Requires org admin role.

Re-enabling a paused endpoint (is_active: true) also resets the consecutive_failures counter, which clears the circuit-breaker state.

Path parameters

org_slug · string · required

Your organization slug.

endpoint_id · string · required

UUID of the endpoint to update.

Request body

url · string

New HTTPS URL. Must start with https://.

name · string

New label for this endpoint.

event_types · string[]

New list of subscribed event types. Replaces the existing list.

is_active · boolean

Set to false to pause deliveries, true to resume. Resuming resets the circuit-breaker counter.

Response — 200

Returns the updated endpoint object (same schema as list, no secret field).

---

Delete a webhook endpoint

cURL

curl -X DELETE https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

DELETE /org/{org_slug}/webhooks/endpoints/{endpoint_id}

Deletes a webhook endpoint. All associated delivery history is cascade-deleted. Requires org admin role.

Path parameters

org_slug · string · required

Your organization slug.

endpoint_id · string · required

UUID of the endpoint to delete.

Response — 204

No body.

---

Rotate signing secret

cURL

curl -X POST https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b/rotate-secret \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

POST /org/{org_slug}/webhooks/endpoints/{endpoint_id}/rotate-secret

Generates a new HMAC signing secret for the endpoint. The old secret is immediately invalidated. Any in-flight deliveries signed with the old key will fail HMAC verification on your receiver. Returns the new secret exactly once. Requires org admin role.

Path parameters

org_slug · string · required

Your organization slug.

endpoint_id · string · required

UUID of the endpoint.

Response — 200

id · string

Endpoint UUID.

secret · string

The new raw HMAC signing key. Store this immediately — it is not returned again.

---

List deliveries

cURL

curl "https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b/deliveries?page=1&page_size=20" \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /org/{org_slug}/webhooks/endpoints/{endpoint_id}/deliveries

Returns paginated delivery history for a webhook endpoint, ordered newest-first.

Path parameters

org_slug · string · required

Your organization slug.

endpoint_id · string · required

UUID of the endpoint.

Query parameters

page · number · default: "1"

Page number (1-indexed).

page_size · number · default: "20"

Number of deliveries per page.

Response — 200

items · object[]

Delivery summaries for the current page.

Show delivery fields

id · string

Delivery UUID.

event_type · string

The event type that triggered this delivery (e.g. "alert.fired").

status · string

Delivery status (e.g. "success", "failed", "pending").

created_at · string

ISO 8601 timestamp when the delivery was enqueued.

attempt_count · number

Total number of HTTP attempts made for this delivery.

count · number

Total number of deliveries for this endpoint (before pagination).

---

Get delivery detail

cURL

curl https://api.agentvista.dev/api/v1/org/my-org/webhooks/deliveries/d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

GET /org/{org_slug}/webhooks/deliveries/{delivery_id}

Returns full detail for a single delivery including all HTTP attempts.

Path parameters

org_slug · string · required

Your organization slug.

delivery_id · string · required

UUID of the delivery.

Response — 200

id · string

Delivery UUID.

event_type · string

The event type that triggered this delivery.

status · string

Overall delivery status.

request_body · object

The exact JSON payload that was sent (or attempted) to your endpoint.

created_at · string

ISO 8601 timestamp when the delivery was enqueued.

attempts · object[]

All HTTP attempts for this delivery, in order.

Show attempt fields

attempt_number · number

Attempt sequence number (1-indexed).

http_status_code · number | null

HTTP response status code from your endpoint, or null if no response was received (e.g. connection timeout).

response_body · string

Response body text from your endpoint.

duration_ms · number | null

Round-trip time in milliseconds.

attempted_at · string

ISO 8601 timestamp of this attempt.

error_message · string

Error description if the attempt failed without an HTTP response.

---

Retry a delivery

cURL

curl -X POST https://api.agentvista.dev/api/v1/org/my-org/webhooks/deliveries/d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a/retry \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

POST /org/{org_slug}/webhooks/deliveries/{delivery_id}/retry

Manually enqueues a retry for any delivery regardless of its current status. Returns 202 immediately — the retry is processed asynchronously. The retry task checks that the endpoint is active before sending.

Path parameters

org_slug · string · required

Your organization slug.

delivery_id · string · required

UUID of the delivery to retry.

Response — 202

queued · boolean

Always true when the retry has been enqueued.

delivery_id · string

UUID of the delivery that was queued for retry.

{
  "queued": true,
  "delivery_id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a"
}