Receiving Webhooks

Understand how webhooks are received and stored by agntdata.

How Webhooks Are Received

When an external service sends a webhook to your endpoint, agntdata:

1. Accepts the HTTP request
2. Stores the payload, headers, and metadata as a “delivery”
3. Returns a 200 OK response to the sender

What Gets Stored

Each delivery includes:

Field	Description
id	Unique delivery identifier
webhookEndpointId	The endpoint that received it
rawPayload	The complete JSON body
headers	HTTP headers from the request
sourceIp	IP address of the sender
createdAt	When the delivery was received
acknowledgedAt	When you marked it as processed (null if pending)

Supported Methods and Formats

HTTP Methods

agntdata webhook endpoints accept:

• POST — Standard webhook delivery

Content Types

• application/json — Parsed and stored as JSON
• Other content types — Stored as { raw: "..." }

JSON payloads are recommended for best compatibility.

Delivery Example

A Stripe webhook delivery might look like:

{
  "id": "del_abc123",
  "webhookEndpointId": "wh_xyz789",
  "workspaceId": "ws_abc123",
  "rawPayload": {
    "id": "evt_1234",
    "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"
}

Response to Senders

On success, agntdata returns:

{
  "received": true,
  "deliveryId": "uuid-..."
}

This ensures external services know the delivery was received and can track it.

Handling Large Payloads

Payloads up to 1 MB are accepted. For larger payloads:

Payloads exceeding 1 MB are rejected with a 413 Payload Too Large error.

If you need to receive larger payloads, consider:

• Asking the sender to paginate or summarize data
• Using a different integration approach
• Contacting us about enterprise limits

Verifying Webhook Signatures

Many services sign their webhooks for security. The signature is typically in a header:

Service	Signature Header
Stripe	stripe-signature
GitHub	x-hub-signature-256
Shopify	x-shopify-hmac-sha256
Twilio	x-twilio-signature

When processing deliveries, verify signatures against the headers field:

const crypto = require('crypto');

function verifyStripeSignature(payload, signature, secret) {
  const [timestamp, hash] = parseStripeSignature(signature);
  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${JSON.stringify(payload)}`)
    .digest('hex');
  return hash === expectedHash;
}

Error Handling

If agntdata can’t process an incoming webhook:

Status	Meaning
200	Success — delivery stored
404	Endpoint not found — check the hookId in the URL
413	Payload too large — exceeds 1 MB limit
500	Server error — will be retried by most senders

Next Steps

Managing Deliveries

Learn how to fetch and acknowledge deliveries.

Creating Endpoints

Set up more webhook endpoints.