Copy page

Getting Started

Export-ready webhooks

Export-ready webhooks

Receive an export.ready notification when your CSV is ready to download. Subscriptions belong to the organization identified by your X-API-Key. They cover all that organization's exports, not individual feeds or a whole white-label. No organization or feed ID is accepted when configuring a webhook.

Only export.ready is supported. Notifications cover exports completed after you register your webhook. Failed notifications do not affect your exports.

Create or test

POST /webhooks

Input	Required	Description
mode	Yes	create or test
url	Yes	Public HTTPS URL, maximum 2,048 characters; no credentials or fragments
enabled	No	Defaults to true; applies only to creation

Code
curl -X POST 'https://intentapi.buyerfeeds.com/webhooks' \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"create","url":"https://example.com/webhooks/exports","enabled":true}'

201 Created

Code
{
  "id": "wh_example",
  "url": "https://example.com/webhooks/exports",
  "event": "export.ready",
  "enabled": true,
  "signing_secret": "whsec_example",
  "created_at": "2026-10-21T10:00:00Z",
  "updated_at": "2026-10-21T10:00:00Z"
}

Store the signing secret securely. It is returned once and never included in list or edit responses. To replace a lost secret, create a replacement webhook and delete the old one.

Test without saving

Code
{ "mode": "test", "url": "https://example.com/webhooks/exports" }

200 OK

Code
{
  "mode": "test",
  "delivered": true,
  "http_status": 200,
  "duration_ms": 184,
  "error": null
}

Test mode sends an unsigned sample with test: true, dummy IDs, and null download fields. No subscription or export is created. enabled is ignored. Test notifications are sent once and are not retried.

A delivery failure also returns 200 with delivered: false, for example:

Code
{
  "mode": "test",
  "delivered": false,
  "http_status": null,
  "duration_ms": 10000,
  "error": "Connection timed out"
}

Never process unsigned tests as real exports. Production events must pass signature verification. Disallowed destinations return 422 before a test is sent.

List

GET /webhooks?limit=25&offset=0

limit defaults to 25 (1–100). offset defaults to 0 (zero or greater).

200 OK

Code
{
  "items": [{
    "id": "wh_example",
    "url": "https://example.com/webhooks/exports",
    "event": "export.ready",
    "enabled": true,
    "created_at": "2026-10-21T10:00:00Z",
    "updated_at": "2026-10-21T10:00:00Z",
    "last_delivery": {
      "event_id": "evt_example",
      "status": "delivered",
      "http_status": 200,
      "attempted_at": "2026-10-21T10:05:00Z",
      "error": null
    }
  }],
  "has_more": false,
  "next_offset": null
}

last_delivery is null before an attempt completes. Its status is delivered, retrying, or failed. Follow next_offset while has_more is true.

Edit

PATCH /webhooks/{webhook_id}

Send at least one field. Omitted fields remain unchanged; null is not accepted.

Code
{ "url": "https://example.com/new-webhook", "enabled": false }

200 OK returns id, url, event, enabled, created_at, and updated_at:

Code
{
  "id": "wh_example",
  "url": "https://example.com/new-webhook",
  "event": "export.ready",
  "enabled": false,
  "created_at": "2026-10-21T10:00:00Z",
  "updated_at": "2026-10-21T11:00:00Z"
}

Disabling cancels pending deliveries and retries. Re-enabling applies to future events only. URL changes apply to pending deliveries; an in-flight request may still finish at the previous URL. The signing secret stays the same.

Delete

DELETE /webhooks/{webhook_id}

No request body. Returns 204 No Content. Pending deliveries and retries are removed; an in-flight request may finish.

Event delivered to your URL

Code
{
  "id": "evt_example",
  "type": "export.ready",
  "test": false,
  "created_at": "2026-10-21T10:05:00Z",
  "data": {
    "export_id": "00000000-0000-4000-8000-000000000001",
    "feed_id": "00000000-0000-4000-8000-000000000002",
    "row_count": 13000,
    "download_url": "https://storage.example/signed-download",
    "download_expires_at": "2026-10-21T11:05:00Z"
  }
}

feed_id may be null for exports not associated with a saved feed. row_count is the number of rows in the CSV. Downloads are gzip-compressed CSV files (.csv.gz). Keep download links private.

Download your file before download_expires_at. Links are valid for up to one hour and cannot outlast the file's availability. Each retry includes a new link with the same event ID and creation time. Notifications cannot be delivered after the file expires.

Verify production signatures

Code
Content-Type: application/json
Webhook-Id: evt_example
Webhook-Timestamp: 1792577100
Webhook-Signature: v1=<hex digest>

Compute HMAC-SHA256 over timestamp + "." + raw_request_body, using the complete whsec_... secret as UTF-8 bytes. Compare signatures in constant time and reject timestamps more than five minutes old. Verify before parsing or processing the body.

Code
import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("Webhook-Timestamp", "")
    try:
        if abs(time.time() - int(timestamp)) > 300:
            return False
    except ValueError:
        return False
    expected = "v1=" + hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, headers.get("Webhook-Signature", ""))

Acknowledgement and retries

Return any 2xx within 10 seconds. Queue your own processing before replying; do not wait for the CSV download. Redirects are not followed. All non-2xx responses, connection failures, and timeouts are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours, measured from the preceding failed attempt. There are at most six attempts. Retry times are approximate.

Delivery is at least once: duplicates and out-of-order events are possible. Deduplicate using id. A successful HTTP response stops retries. Inspect last_delivery for failures; no manual replay endpoint is included.

Errors and limits

Status	Meaning
401	Invalid or inactive API key
404	Webhook missing or belongs to another organization
422	Invalid fields, unresolved hostname, or disallowed destination
429	Organization rate limit exceeded; observe Retry-After

Tests allow 10 requests per minute per organization. Creation and updates each allow 30 per minute. Invalid destination requests also count toward these limits.

Code
{ "detail": "Webhook URL must resolve only to public addresses." }

Use a publicly reachable HTTPS endpoint with a valid certificate. Localhost and private-network URLs are not supported.