Webhooks API - AgentVista

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

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

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

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

string

Endpoint UUID.

secret

string

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

List deliveries

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

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

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 -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"
}

​Create a webhook endpoint

​Path parameters

​Request body

​Response — 201

​List webhook endpoints

​Path parameters

​Response — 200

​Update a webhook endpoint

​Path parameters

​Request body

​Response — 200

​Delete a webhook endpoint

​Path parameters

​Response — 204

​Rotate signing secret

​Path parameters

​Response — 200

​List deliveries

​Path parameters

​Query parameters

​Response — 200

​Get delivery detail

​Path parameters

​Response — 200

​Retry a delivery

​Path parameters

​Response — 202

Create a webhook endpoint

Path parameters

Request body

Response — 201

List webhook endpoints

Path parameters

Response — 200

Update a webhook endpoint

Path parameters

Request body

Response — 200

Delete a webhook endpoint

Path parameters

Response — 204

Rotate signing secret

Path parameters

Response — 200

List deliveries

Path parameters

Query parameters

Response — 200

Get delivery detail

Path parameters

Response — 200

Retry a delivery

Path parameters

Response — 202