Webhooks: Introduction

DataDoe Webhooks send an HTTPS POST request to an endpoint you control when selected events happen. Use them to start automations, sync events into your enterprise resource planning (ERP) or warehouse management system (WMS), or start downstream jobs without polling DataDoe or Amazon.

Which webhook type do I need?

DataDoe has 2 webhook types. You choose the type when you create a webhook. To use another type, create a new webhook.

	Business webhooks	Platform webhooks
Type in DataDoe	Amazon	Platform
Events	Amazon events for your Sellers and Vendors, such as orders, listings, offers and inventory	Events about your Organization, such as initial loads, AI Tokens, Actions, billing and access
Scope	The Sellers and Vendors you select	Your whole Organization, including Sellers and Vendors you add later
Who can manage them	Users with the Webhooks permission	Organization Admins only
Cost	0.05 AI Tokens for each delivered message	Free, 0 AI Tokens
Messages in a request	Up to 100	1
Guide	Webhooks: Business	Webhooks: Platform

The webhook catalog lists every message type with its summary and payload schema. Platform message types have the Platform (free) label. Amazon message types that can send many events have the High volume label. AI agents can read the machine-readable catalog (opens in a new tab).

How do I set up a webhook?

Open Integrations > Webhooks (opens in a new tab).
Select New webhook and choose the webhook type.
Enter a name and the HTTPS target URL of your endpoint.
Select the message types. For a Business webhook, also select the Sellers and Vendors.
Add a secret header name and value. This step is optional, but we recommend it for every webhook.
Save the webhook.

A new webhook is Active. It receives events that happen after you save it. You can create several webhooks, for example one for your ERP and another for an internal queue. DataDoe delivers an event to each active webhook that subscribes to it.

What are the target URL requirements?

Your target URL must:

use HTTPS
use a public domain name, not an IP address, localhost or a name without a dot
resolve only to public IP addresses
accept POST requests

DataDoe checks the URL when you save the webhook and checks its DNS again before each delivery. A domain that resolves to a private network address fails delivery. DataDoe does not follow redirects, so a 3xx response is a failed delivery.

How do I secure my webhook?

Add a secret HTTP header so that your endpoint can reject forged requests. In Integrations > Webhooks (opens in a new tab), set a header name and a long, random value when you create or edit a webhook. DataDoe sends this header with every request.

Store the value securely on your server. Compare the incoming header with the stored value before you process the request. Reject the request if the header is missing or wrong.

What does DataDoe send to my endpoint?

DataDoe sends an HTTPS POST with Content-Type: application/json. The body has this shape:

json

1{
2    "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
3    "organizationId": "11111111-1111-4111-8111-111111111111",
4    "webhookId": "33333333-3333-4333-8333-333333333333",
5    "messages": [
6        {
7            "organizationId": "11111111-1111-4111-8111-111111111111",
8            "sellerOrVendorId": "22222222-2222-4222-8222-222222222222",
9            "messageId": "44444444-4444-4444-8444-444444444444",
10            "messageType": "AMAZON_ORDER_UPDATE",
11            "messageSummary": {},
12            "messageData": {}
13        }
14    ]
15}

Field	Meaning
`deliveryId`	Unique ID of this HTTPS request. It changes for each request.
`organizationId`	Your DataDoe Organization.
`webhookId`	The webhook that receives this request.
`messages`	The events in this request.
`sellerOrVendorId`	The DataDoe Seller or Vendor of the event. Platform events about the Organization use `null`.
`messageId`	Unique ID of a single event. Use it to detect a message you already processed.
`messageType`	The event type, for example `AMAZON_ORDER_UPDATE`.
`messageSummary`	Short metadata about the event. Its fields depend on the message type.
`messageData`	The event payload. Its fields depend on the message type.

The webhook catalog shows the messageSummary and messageData fields of each message type.

What should my endpoint return?

Return any 2xx status within 30 seconds to confirm that you received the request. Then process the messages separately, so that slow processing does not cause a timeout.

DataDoe treats any other status, a timeout or a network error as a failed delivery.

What happens when a delivery fails?

When a delivery fails, DataDoe:

Pauses the webhook.
Emails the active Organization Admins.

DataDoe does not retry a failed request. A paused webhook does not receive events, and DataDoe does not send them later. After you fix your endpoint, open Integrations > Webhooks (opens in a new tab) and select Resume. The webhook then receives new events.

Webhooks can also pause for other reasons, such as missing AI Tokens or lost access. See Webhooks: Business and Webhooks: Platform for the details of each type.

If you think a failed delivery is caused by DataDoe, use the contact form (opens in a new tab).

Webhooks complement the scheduled and real-time data pipelines described in Data Fetch Periods. They are the recommended way to get real-time updates.

Where can I get help?

Use the contact form (opens in a new tab).