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

# Managing Deliveries

> View, process, and acknowledge webhook deliveries from the dashboard or the API.

## Two Ways to Consume Deliveries

Deliveries can be consumed two ways:

* **Dashboard** — view, inspect, and acknowledge deliveries interactively.
* **API** — poll `GET /v1/webhook-endpoints/deliveries` with an agntdata API key so agents and backends can process webhooks programmatically.

Pick whichever fits your workflow; both read from the same underlying inbox.

## Viewing Deliveries

The Webhooks page in the dashboard shows all deliveries:

1. Navigate to **Webhooks** in the sidebar
2. Click on an endpoint to see its deliveries
3. Click on a delivery to view the full payload

### Delivery Details

Each delivery shows:

| Field     | Description                    |
| --------- | ------------------------------ |
| ID        | Unique delivery identifier     |
| Received  | When the delivery was received |
| Status    | Pending or Acknowledged        |
| Source IP | IP address of the sender       |
| Payload   | The complete JSON body         |
| Headers   | HTTP headers from the request  |

## Filtering Deliveries

Use the dashboard filters to find specific deliveries:

* **By Endpoint** — Select a specific endpoint to view its deliveries only
* **By Status** — Filter by pending (unacknowledged) or acknowledged

## Acknowledging Deliveries

Acknowledging a delivery marks it as processed. This helps you track which webhooks you've handled.

### Single Delivery

1. Click on the delivery to open details
2. Click **Acknowledge** button
3. The delivery is marked as processed

### Bulk Acknowledgment

1. Select multiple deliveries using the checkboxes
2. Click **Acknowledge Selected**
3. All selected deliveries are marked as processed

## Delivery Payload

Click on any delivery to inspect its full payload:

```json theme={null}
{
  "id": "del_abc123",
  "webhookEndpointId": "wh_xyz789",
  "rawPayload": {
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_5678",
        "amount": 2000,
        "currency": "usd"
      }
    }
  },
  "headers": {
    "content-type": "application/json",
    "stripe-signature": "t=1699999999,v1=abc123..."
  },
  "sourceIp": "54.187.174.169",
  "acknowledgedAt": null,
  "createdAt": "2024-01-15T10:30:00Z"
}
```

## Programmatic Access

Agents and backend services can fetch and acknowledge deliveries using any agntdata API key. All endpoints live under the `/v1/webhook-endpoints` prefix on `https://api.agntdata.dev` and require `Authorization: Bearer <API_KEY>`.

### List Deliveries

```http theme={null}
GET /v1/webhook-endpoints/deliveries
```

Query parameters:

| Name             | Type             | Description                                   |
| ---------------- | ---------------- | --------------------------------------------- |
| `endpointId`     | string           | Filter to a single endpoint                   |
| `unacknowledged` | `true` / `false` | Only return unacknowledged deliveries         |
| `limit`          | number           | Page size (default 50, max 100)               |
| `cursor`         | string           | Pagination cursor returned by a previous call |

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": "del_abc123",
        "webhookEndpointId": "wh_xyz789",
        "workspaceId": "ws_abc123",
        "rawPayload": { "type": "payment_intent.succeeded" },
        "headers": { "content-type": "application/json" },
        "sourceIp": "54.187.174.169",
        "acknowledgedAt": null,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "nextCursor": "2024-01-15T10:29:59Z"
  }
}
```

When `nextCursor` is non-null, pass it back as `cursor` to fetch the next page. When it is `null`, you've reached the end.

### Acknowledge One Delivery

```http theme={null}
POST /v1/webhook-endpoints/deliveries/:id/ack
```

### Acknowledge Many Deliveries

```http theme={null}
POST /v1/webhook-endpoints/deliveries/ack
Content-Type: application/json

{ "ids": ["del_abc123", "del_abc124"] }
```

### Polling Example

```bash theme={null}
curl -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  "https://api.agntdata.dev/v1/webhook-endpoints/deliveries?unacknowledged=true&limit=100"
```

A typical agent loop:

1. `GET /v1/webhook-endpoints/deliveries?unacknowledged=true&limit=100`
2. Process each delivery idempotently.
3. `POST /v1/webhook-endpoints/deliveries/ack` with the IDs you successfully handled.
4. If `nextCursor` is returned, page forward; otherwise wait and poll again.

## Pagination

Deliveries are paginated with a maximum of 100 per page (default 50). Both the dashboard and the API return a `nextCursor` you can use to page through older deliveries.

## Best Practices

<AccordionGroup>
  <Accordion title="Process Regularly">
    Check and process deliveries regularly to stay on top of incoming webhooks.
  </Accordion>

  <Accordion title="Handle Failures Gracefully">
    If processing fails, don't acknowledge the delivery. Retry processing later.
  </Accordion>

  <Accordion title="Verify Signatures">
    Before processing sensitive data, verify the webhook signature from the `headers` field.
  </Accordion>

  <Accordion title="Idempotent Processing">
    Design your processing to be idempotent — safe to run multiple times with the same data.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhooks Overview" icon="webhook" href="/webhooks/overview">
    Learn more about agntdata webhooks.
  </Card>

  <Card title="Creating Endpoints" icon="plus" href="/webhooks/endpoints">
    Set up more webhook endpoints.
  </Card>
</CardGroup>