> ## Documentation Index
> Fetch the complete documentation index at: https://moonshotfactory.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Warning>
  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.
</Warning>

***

## Create a webhook endpoint

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

`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

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

### Request body

<ParamField body="url" type="string" required>
  HTTPS URL that AgentVista will POST event payloads to. Must start with `https://` — HTTP URLs are rejected.
</ParamField>

<ParamField body="name" type="string">
  Human-readable label for this endpoint.
</ParamField>

<ParamField body="event_types" type="string[]" required>
  List of event types to deliver to this endpoint. Must contain at least one entry (e.g. `["alert.fired"]`).
</ParamField>

### Response — 201

<ResponseField name="id" type="string">
  UUID of the new endpoint.
</ResponseField>

<ResponseField name="url" type="string">
  The registered HTTPS URL.
</ResponseField>

<ResponseField name="name" type="string">
  Endpoint label.
</ResponseField>

<ResponseField name="event_types" type="string[]">
  Subscribed event types.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Always `true` on creation.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="secret" type="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.
</ResponseField>

```json Example response theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

### Response — 200

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

<ResponseField name="id" type="string">Endpoint UUID.</ResponseField>
<ResponseField name="url" type="string">Registered HTTPS URL.</ResponseField>
<ResponseField name="name" type="string">Endpoint label.</ResponseField>
<ResponseField name="event_types" type="string[]">Subscribed event types.</ResponseField>
<ResponseField name="is_active" type="boolean">Whether the endpoint receives deliveries.</ResponseField>

<ResponseField name="consecutive_failures" type="number">
  Number of consecutive failed delivery attempts. If this reaches the circuit-breaker threshold, the endpoint is automatically paused.
</ResponseField>

<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>

***

## Update a webhook endpoint

<CodeGroup>
  ```bash Pause endpoint theme={null}
  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}'
  ```

  ```bash Update URL and events theme={null}
  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 '{
      "url": "https://hooks.example.com/agentvista-v2",
      "event_types": ["alert.fired"]
    }'
  ```
</CodeGroup>

`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

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

<ParamField path="endpoint_id" type="string" required>
  UUID of the endpoint to update.
</ParamField>

### Request body

<ParamField body="url" type="string">
  New HTTPS URL. Must start with `https://`.
</ParamField>

<ParamField body="name" type="string">
  New label for this endpoint.
</ParamField>

<ParamField body="event_types" type="string[]">
  New list of subscribed event types. Replaces the existing list.
</ParamField>

<ParamField body="is_active" type="boolean">
  Set to `false` to pause deliveries, `true` to resume. Resuming resets the circuit-breaker counter.
</ParamField>

### Response — 200

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

***

## Delete a webhook endpoint

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.agentvista.dev/api/v1/org/my-org/webhooks/endpoints/e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`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

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

<ParamField path="endpoint_id" type="string" required>
  UUID of the endpoint to delete.
</ParamField>

### Response — 204

No body.

***

## Rotate signing secret

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

`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

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

<ParamField path="endpoint_id" type="string" required>
  UUID of the endpoint.
</ParamField>

### Response — 200

<ResponseField name="id" type="string">
  Endpoint UUID.
</ResponseField>

<ResponseField name="secret" type="string">
  The new raw HMAC signing key. **Store this immediately — it is not returned again.**
</ResponseField>

***

## List deliveries

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

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

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

### Path parameters

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

<ParamField path="endpoint_id" type="string" required>
  UUID of the endpoint.
</ParamField>

### Query parameters

<ParamField query="page" type="number" default="1">
  Page number (1-indexed).
</ParamField>

<ParamField query="page_size" type="number" default="20">
  Number of deliveries per page.
</ParamField>

### Response — 200

<ResponseField name="items" type="object[]">
  Delivery summaries for the current page.

  <Expandable title="delivery fields">
    <ResponseField name="id" type="string">Delivery UUID.</ResponseField>
    <ResponseField name="event_type" type="string">The event type that triggered this delivery (e.g. `"alert.fired"`).</ResponseField>
    <ResponseField name="status" type="string">Delivery status (e.g. `"success"`, `"failed"`, `"pending"`).</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 timestamp when the delivery was enqueued.</ResponseField>
    <ResponseField name="attempt_count" type="number">Total number of HTTP attempts made for this delivery.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="count" type="number">
  Total number of deliveries for this endpoint (before pagination).
</ResponseField>

***

## Get delivery detail

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/org/my-org/webhooks/deliveries/d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

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

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

### Path parameters

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

<ParamField path="delivery_id" type="string" required>
  UUID of the delivery.
</ParamField>

### Response — 200

<ResponseField name="id" type="string">
  Delivery UUID.
</ResponseField>

<ResponseField name="event_type" type="string">
  The event type that triggered this delivery.
</ResponseField>

<ResponseField name="status" type="string">
  Overall delivery status.
</ResponseField>

<ResponseField name="request_body" type="object">
  The exact JSON payload that was sent (or attempted) to your endpoint.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp when the delivery was enqueued.
</ResponseField>

<ResponseField name="attempts" type="object[]">
  All HTTP attempts for this delivery, in order.

  <Expandable title="attempt fields">
    <ResponseField name="attempt_number" type="number">Attempt sequence number (1-indexed).</ResponseField>
    <ResponseField name="http_status_code" type="number | null">HTTP response status code from your endpoint, or `null` if no response was received (e.g. connection timeout).</ResponseField>
    <ResponseField name="response_body" type="string">Response body text from your endpoint.</ResponseField>
    <ResponseField name="duration_ms" type="number | null">Round-trip time in milliseconds.</ResponseField>
    <ResponseField name="attempted_at" type="string">ISO 8601 timestamp of this attempt.</ResponseField>
    <ResponseField name="error_message" type="string">Error description if the attempt failed without an HTTP response.</ResponseField>
  </Expandable>
</ResponseField>

***

## Retry a delivery

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

`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

<ParamField path="org_slug" type="string" required>
  Your organization slug.
</ParamField>

<ParamField path="delivery_id" type="string" required>
  UUID of the delivery to retry.
</ParamField>

### Response — 202

<ResponseField name="queued" type="boolean">
  Always `true` when the retry has been enqueued.
</ResponseField>

<ResponseField name="delivery_id" type="string">
  UUID of the delivery that was queued for retry.
</ResponseField>

```json theme={null}
{
  "queued": true,
  "delivery_id": "d1e2f3a4-b5c6-4d7e-8f9a-0b1c2d3e4f5a"
}
```