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:

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

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:

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

POST /v1/webhook-endpoints/deliveries/:id/ack

Acknowledge Many Deliveries

POST /v1/webhook-endpoints/deliveries/ack
Content-Type: application/json

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

Polling Example

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

Process Regularly

Check and process deliveries regularly to stay on top of incoming webhooks.

Handle Failures Gracefully

If processing fails, don’t acknowledge the delivery. Retry processing later.

Verify Signatures

Before processing sensitive data, verify the webhook signature from the headers field.

Idempotent Processing

Design your processing to be idempotent — safe to run multiple times with the same data.

Next Steps

Webhooks Overview

Learn more about agntdata webhooks.

Creating Endpoints

Set up more webhook endpoints.