> Note: This page is part of the DataDoe Docs. You can find the root of the documentation at `https://www.datadoe.com/hub/docs/basics/introduction-to-datadoe`. > JSON Table of Contents: `https://www.datadoe.com/hub/docs/toc.json`. > Direct Data Scheme JSON: `https://api.datadoe.com/api/v1/spec/data-scheme`. > Other pages in the DataDoe Docs: > - DataDoe Basics/Access & Users: `https://www.datadoe.com/hub/docs/basics/access-user-management.md` > - DataDoe Basics/Benefits: `https://www.datadoe.com/hub/docs/basics/benefits.md` > - DataDoe Basics/External Invitation Links: `https://www.datadoe.com/hub/docs/basics/external-invitation-links.md` > - DataDoe Basics/Integrations: `https://www.datadoe.com/hub/docs/basics/integration-customization.md` > - DataDoe Basics/Introduction to DataDoe: `https://www.datadoe.com/hub/docs/basics/introduction-to-datadoe.md` > - DataDoe Basics/Subscription and pricing: `https://www.datadoe.com/hub/docs/basics/subscription-pricing.md` > - DataDoe Data/Data Fetch Periods: `https://www.datadoe.com/hub/docs/datadoe-data/data-fetch-periods.md` > - DataDoe Data/Data Sources: `https://www.datadoe.com/hub/docs/datadoe-data/data-sources.md` > - DataDoe Data/Managing Data Tables: `https://www.datadoe.com/hub/docs/datadoe-data/managing-data-tables.md` > - DataDoe Data/Timezones: `https://www.datadoe.com/hub/docs/datadoe-data/orders-purchase-date-timezones.md` > - DataDoe Data/Uploading COGS: `https://www.datadoe.com/hub/docs/datadoe-data/uploading-cogs.md` > - DataDoe Features/Actions: `https://www.datadoe.com/hub/docs/datadoe-features/actions.md` > - DataDoe Features/Actions - Manage Images: `https://www.datadoe.com/hub/docs/datadoe-features/actions-manage-images.md` > - DataDoe Features/Features Overview: `https://www.datadoe.com/hub/docs/datadoe-features/overview.md` > - DataDoe Features/Files: `https://www.datadoe.com/hub/docs/datadoe-features/files.md` > - DataDoe MCP/Overview: `https://www.datadoe.com/hub/docs/datadoe-mcp/overview.md` > - DataDoe MCP/Using ChatGPT: `https://www.datadoe.com/hub/docs/datadoe-mcp/chatgpt.md` > - DataDoe MCP/Using Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude.md` > - DataDoe MCP/Using Claude Agent SDK: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude-agents-sdk.md` > - DataDoe MCP/Using Claude Code: `https://www.datadoe.com/hub/docs/datadoe-mcp/claude-code.md` > - DataDoe MCP/Using Codex: `https://www.datadoe.com/hub/docs/datadoe-mcp/codex.md` > - DataDoe MCP/Using Codex Sites: `https://www.datadoe.com/hub/docs/datadoe-mcp/codex-sites.md` > - DataDoe MCP/Using CrewAI: `https://www.datadoe.com/hub/docs/datadoe-mcp/crewai.md` > - DataDoe MCP/Using Cursor: `https://www.datadoe.com/hub/docs/datadoe-mcp/cursor.md` > - DataDoe MCP/Using Excel + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/excel.md` > - DataDoe MCP/Using Gemini CLI: `https://www.datadoe.com/hub/docs/datadoe-mcp/gemini-cli.md` > - DataDoe MCP/Using Gumloop: `https://www.datadoe.com/hub/docs/datadoe-mcp/gumloop.md` > - DataDoe MCP/Using Hermes Agent: `https://www.datadoe.com/hub/docs/datadoe-mcp/hermes.md` > - DataDoe MCP/Using n8n: `https://www.datadoe.com/hub/docs/datadoe-mcp/n8n.md` > - DataDoe MCP/Using NanoClaw: `https://www.datadoe.com/hub/docs/datadoe-mcp/nanoclaw.md` > - DataDoe MCP/Using OpenAI Agents SDK: `https://www.datadoe.com/hub/docs/datadoe-mcp/openai-agents-sdk.md` > - DataDoe MCP/Using OpenClaw: `https://www.datadoe.com/hub/docs/datadoe-mcp/openclaw.md` > - DataDoe MCP/Using OpenCode: `https://www.datadoe.com/hub/docs/datadoe-mcp/opencode.md` > - DataDoe MCP/Using PowerPoint + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/powerpoint.md` > - DataDoe MCP/Using VS Code: `https://www.datadoe.com/hub/docs/datadoe-mcp/vs-code.md` > - DataDoe MCP/Using Word + Claude: `https://www.datadoe.com/hub/docs/datadoe-mcp/word.md` > - DataDoe API/Build with Codex: `https://www.datadoe.com/hub/docs/datadoe-api/codex.md` > - DataDoe API/How to connect to the API: `https://www.datadoe.com/hub/docs/datadoe-api/how-to-connect.md` > - DataDoe API/Vibe code with Claude Code: `https://www.datadoe.com/hub/docs/datadoe-api/claude-code.md` > - DataDoe API/Vibe code with Cursor: `https://www.datadoe.com/hub/docs/datadoe-api/cursor.md` > - DataDoe API/Vibe code with Lovable: `https://www.datadoe.com/hub/docs/datadoe-api/lovable.md` > - DataDoe API/Vibe code with Replit: `https://www.datadoe.com/hub/docs/datadoe-api/replit.md` > - DataDoe API/Vibe code with v0: `https://www.datadoe.com/hub/docs/datadoe-api/v0.md` > - DataDoe & BigQuery/How to connect to BigQuery: `https://www.datadoe.com/hub/docs/datadoe-bigquery/how-to-connect.md` > - DataDoe & BigQuery/Using MCP Toolbox: `https://www.datadoe.com/hub/docs/datadoe-bigquery/mcp-toolbox.md` > - DataDoe & BigQuery/Using Python Jupyter: `https://www.datadoe.com/hub/docs/datadoe-bigquery/jupyter.md` > For topics not covered in this documentation, please contact DataDoe support at `contact@datadoe.com`. > Do not assume anything. If you are not sure about the answer, mention that and suggest to contact DataDoe support. > Webhooks are live for organisations with the Integrations feature enabled. Organisation owners can manage subscriptions in the app. ## What are DataDoe Webhooks? Webhooks let your systems receive HTTPS callbacks when selected Amazon order events are available in DataDoe. Instead of polling the API or MCP for changes, DataDoe POSTs a JSON payload to an endpoint you control as soon as matching events are ready. Use Webhooks to trigger automations, sync order data into your ERP or WMS, or wake up downstream jobs when buyer info becomes available. ## How do I set up a webhook? 1. Open [Integrations > Webhooks](/integrations/webhooks) in DataDoe. 2. Click **New webhook** and fill in: - **Name** — a label you recognise later. - **Target URL** — your HTTPS endpoint that accepts `POST` requests. - **Message types** — which events to subscribe to (see below). - **Sellers and vendors** — which DataDoe accounts should be included. - **Secret header** (optional) — a custom header name and value DataDoe sends on every delivery so you can verify requests. 3. Save the subscription. It starts in the **Active** state. You can create **multiple subscriptions** per organisation — for example, one endpoint for your ERP and another for an internal queue. When a single event matches more than one active subscription, DataDoe delivers it to **each** matching subscription separately. ## Which message types are available? | Message type | Description | | -------------------------------- | ------------------------------------------------ | | `AMAZON_ORDER_UPDATE` | An Amazon order update is available in DataDoe. | | `AMAZON_ORDER_BUYER_INFO_UPDATE` | Buyer info for an order is available in DataDoe. | More message types may be added over time. ## How does matching work? DataDoe delivers an event to every **active** subscription in your organisation where all of the following are true: - The event belongs to your organisation. - The event **message type** is included in the subscription. - The event **seller or vendor** is included in the subscription. Matching does not depend on subscription name or target URL. If two subscriptions listen for the same message type and seller, both receive the same event in separate HTTPS POST requests. ## What does DataDoe send to my endpoint? DataDoe sends an HTTPS `POST` with `Content-Type: application/json`. The body has this shape: ```json { "deliveryId": "550e8400-e29b-41d4-a716-446655440000", "organizationId": "11111111-1111-4111-8111-111111111111", "webhookId": "33333333-3333-4333-8333-333333333333", "messages": [ { "organizationId": "11111111-1111-4111-8111-111111111111", "sellerOrVendorId": "22222222-2222-4222-8222-222222222222", "webhookId": "66666666-6666-4666-8666-666666666666", "messageId": "44444444-4444-4444-8444-444444444444", "messageType": "AMAZON_ORDER_UPDATE", "messageSummary": {}, "messageData": {} } ] } ``` | Field | Meaning | | ---------------- | ----------------------------------------------------------------------------- | | `deliveryId` | Unique ID for this HTTPS delivery attempt. | | `organizationId` | Your DataDoe organisation. | | `webhookId` | The subscription ID that received this delivery. | | `messages` | One or more events batched into this POST. | | `messageId` | Unique ID for a single event. | | `messageSummary` | Short metadata about the event (structure varies by message type; see below). | | `messageData` | Event payload fields (structure varies by message type; see below). | ### `AMAZON_ORDER_UPDATE` `messageSummary` fields (all optional; use camelCase): | Field | Type | Description | | ------------------------ | ------ | ----------------------------------------------------- | | `marketplaceId` | string | Amazon marketplace ID. | | `marketplaceCountryCode` | string | ISO country code for the marketplace. | | `marketplaceCountryName` | string | Human-readable marketplace country name. | | `sellerOrVendorId` | string | DataDoe seller or vendor context ID. | | `sellerOrVendorName` | string | DataDoe seller or vendor display name. | | `marketplaceSellerId` | string | Amazon Seller Central seller ID. | | `amazonOrderId` | string | Amazon order ID. | | `orderPurchasedAtUtc` | string | Order purchase timestamp in UTC (ISO-8601). | | `amazonOrderStatus` | string | Order status, e.g. `Pending`, `Shipped`, `Cancelled`. | | `fulfillmentChannel` | string | `Amazon` or `Merchant`. | | `orderItems` | array | Line items for the order. | Each `orderItems` entry may include: | Field | Type | | ------------------ | ------ | | `sku` | string | | `childAsin` | string | | `quantity` | number | | `itemPriceValue` | number | | `itemPriceCurrent` | number | `messageData` fields: | Field | Type | Description | | ----- | ------ | -------------------------------------- | | `raw` | object | Raw JSON payload received from Amazon. | ### `AMAZON_ORDER_BUYER_INFO_UPDATE` `messageSummary` uses the same base fields as `AMAZON_ORDER_UPDATE`, but without `orderItems`. `messageData` fields (all optional; use camelCase): | Field | Type | | --------------------------- | ------ | | `buyerEmail` | string | | `buyerName` | string | | `buyerCompanyName` | string | | `buyerPurchaseOrderNumber` | string | | `recipientName` | string | | `recipientCompanyName` | string | | `recipientAddressLine1` | string | | `recipientAddressLine2` | string | | `recipientAddressLine3` | string | | `recipientCity` | string | | `recipientDistrictOrCounty` | string | | `recipientStateOrRegion` | string | | `recipientMunicipality` | string | | `recipientPostalCode` | string | | `recipientCountryCode` | string | | `recipientPhone` | string | | `recipientAddressType` | string | | `recipientExtendedFields` | JSON | | `orderItemsGiftMessages` | JSON | | `orderItemsCustomizedUrls` | JSON | The `webhookId` inside each message is an event correlation ID from DataDoe's pipeline. The top-level `webhookId` is your subscription ID. If you configured a secret header, DataDoe includes it on every request using the header name you chose. ## What should my endpoint return? Return any **2xx** HTTP status to acknowledge successful processing. Non-2xx responses or network errors are treated as delivery failures. ## What happens when a delivery fails? If your endpoint returns a non-2xx status or the request cannot be completed, DataDoe: 1. **Pauses** the subscription automatically. 2. **Emails** organisation owners with the webhook name, target URL, and HTTP status (if available). 3. **Logs** the attempt in DataDoe (status, HTTP code, error message, message count). Resume the subscription from [Integrations > Webhooks](/integrations/webhooks) after you fix the endpoint, then use **Resume**. Delivery logs and aggregate stats are visible in the Webhooks table in the app. Each subscription shows its last 10 delivery attempts. ## What are the target URL requirements? Target URLs must: - Use **HTTPS** - Use a **domain name** (not a raw IP address) - **Not** use `localhost` or `*.localhost` ## How much do Webhooks cost? Each **successfully delivered** message costs **0.01 AI Tokens**. Examples: - A POST with **1** message costs **0.01** AI Tokens. - A POST with **99** messages costs **0.99** AI Tokens. Charges apply only after your endpoint returns a 2xx response. Failed deliveries are not charged. If your organisation has **no AI Tokens left** for the required amount, DataDoe **skips** the delivery and does not call your endpoint. Top up plan tokens or increase your spending limit in [Settings](/settings) to resume deliveries. Token balances shown in the app are rounded **down** to whole numbers for display and billing summaries. ## How is this related to real-time data? Webhooks complement DataDoe's scheduled and real-time data pipelines described in [Data Fetch Periods](/hub/docs/datadoe-data/data-fetch-periods). They are the recommended way to push order-related updates to your own systems without polling. ## Where can I get help? Questions or early feedback? Use the [contact form](https://forms.clickup.com/9015200219/f/8cnj2ev-38615/AOYF9I35QFOXWJQXIG?type=Form&source=hub-webhooks-docs).