Webhooks: Platform

Platform webhooks send free notifications about your Organization to an HTTPS endpoint you control. Use them to automate onboarding, monitor AI Token availability, track Actions and payments, or record access changes. In DataDoe, their webhook type is Platform.

Read Webhooks: Introduction first. It covers setup, target URL requirements, security and the request body for every webhook type.

Only Organization Admins can create, view, edit, pause, resume, delete, or reassign Platform webhooks. The Platform webhooks permission stays enabled for Admins and cannot be granted to other Roles or service accounts. API and MCP keys cannot administer these subscriptions.

Platform subscriptions cover your whole Organization, including Sellers and Vendors you add later. Business webhooks for Amazon events are separate and use selected Sellers and Vendors. To change the webhook type, create a new subscription.

Set up a Platform webhook

1. Open Integrations > Webhooks (opens in a new tab).
2. Select New webhook, then choose Platform as the webhook type.
3. Enter a name and your public HTTPS target URL.
4. Select the message types you need.
5. Optionally, add a secret header name and a long, random value. We recommend it.
6. Save the subscription.

If you add a secret header, check it in your endpoint before you process each request.

Your endpoint must meet the target URL requirements. DataDoe rejects IP addresses and localhost when you save. It checks DNS again before each delivery, so a hostname that resolves to a private network address fails delivery and pauses the subscription. Redirects are not followed. Platform subscriptions do not need a Seller or Vendor selection. New subscriptions receive future matching events only.

Creating a subscription requires the usual Integrations eligibility. Existing Platform subscriptions can keep delivering after a paid subscription ends or becomes delinquent, while their execution owner remains an active Organization Admin and your DataDoe access is not suspended or terminated. Admins can still manage them from Webhooks (opens in a new tab), including through the Manage Platform webhooks link on the subscription landing page.

Free delivery

Every Platform notification costs 0 AI Tokens. Delivery does not use reserved tokens, token bundles, or your spending limit, and zero balance does not pause it.

An Action, query, Export, or other operation that your system starts in response retains its normal cost. Business webhook delivery costs 0.05 AI Tokens per delivered message. See Subscription and pricing.

Event catalog

All 28 message types below have the Platform (free) label in the webhook catalog. Expand a type there to see every field and download its JSON Schema. The machine-readable catalog (opens in a new tab) includes the same contracts.

Initial load and account changes

Initial-load notifications describe the seller or vendor account, rather than each underlying connection. They cover the participating Seller Central, Vendor Central, and Amazon Ads sources used by the account's initial-load phases. They do not claim that Amazon Ads DSP or Amazon Marketing Cloud has completed.

A phase completes when all participating sources reach it. An account with no participating sources has no completion event. Connecting or replacing a participating source starts a new load generation. Removing a source can complete an outstanding phase without repeating a phase already completed in that generation. Routine refreshes and temporary readiness changes do not start another generation.

Reauthorization events describe explicit Amazon connection authorization. Refreshing an access token does not produce a reauthorization success event. Shared connections can produce one contextual message per affected account, with the same operation identifiers.

An edited-account event includes only the names of changed AI instruction or file fields, never their contents. Removed-account events retain a safe account snapshot even though that account can no longer be retrieved.

Tokens and replenishment

The four downward alerts fire at 50%, 30%, 10%, and 0 spendable tokens. Repeated consumption below a threshold does not repeat its alert. Availability rising above that threshold arms it again. One balance change can cross several thresholds and produce several messages.

The balance includes your plan, unexpired purchased bundles, and token capacity available through your spending limit. Reservations reduce spendable availability. Committing a reservation does not deduct that availability twice.

The calculation uses the unrounded token amounts:

available = max(0,
  plan.remaining - plan.reserved
  + bundles.remaining - bundles.reserved
  + max(0, spendingLimit.tokenCapacity - spendingLimit.used - spendingLimit.reserved))
capacity = plan.limit + bundles.capacity + spendingLimit.tokenCapacity
remainingPercent = clamp(100 * available / capacity, 0, 100)

When capacity is zero, remainingPercent is null. Exhaustion still means that spendable availability reached zero. Bundle capacity includes exhausted bundles until they expire, so spending a bundle's last token does not shrink the percentage denominator. Spending-limit capacity is converted to tokens, not treated as a currency amount.

Replenishment reports an actual increase in availability after a renewal, reset, plan change, bundle credit, spending-limit increase, credit, or adjustment. A successful payment alone is not replenishment until tokens are available. Releasing a reservation can arm an alert again but is not a replenishment event. Demo balances do not generate token alerts.

A new subscription does not receive old low-balance alerts. Replenishment never automatically resumes Amazon webhooks that paused for low tokens.

Actions, billing, access, and credentials

Action events describe a stored terminal outcome. Queued, waiting, token-blocked, canceled, and unstored dry-run Actions do not produce these outcome notifications. The payload preserves the Action's status and distinguishes warning-only completion from partial success. It contains safe counts and identifiers, not raw requests, provider responses, or buyer information.

A failed-payment event identifies one confirmed payment obligation. Recovery refers to payment of that same obligation, not another successful purchase. Subscription changes report effective changes rather than identical refreshes. Scheduling cancellation does not mean the subscription has ended. A specific cancellation or end event can accompany a subscription-changed event from the same operation.

Permission events describe effective access changes for each affected user. Large changes have several parts. Collect every part for the changeId before applying it. If a part is missing, or you detect a version gap, refresh access state through an authorized DataDoe interface.

Key events contain safe metadata only. Natural key expiry is not a revocation event. MCP OAuth completion means a successful first authorization-code exchange for a new authorization, including the granted scopes. Unused consent codes and token refreshes do not produce it.

Delivery envelope

Each HTTP POST contains one Platform message in the messages array. Each matching subscription receives its own delivery attempt.

This synthetic example reports an API key creation:

1{
2    "deliveryId": "11111111-1111-4111-8111-111111111111",
3    "organizationId": "22222222-2222-4222-8222-222222222222",
4    "webhookId": "33333333-3333-4333-8333-333333333333",
5    "messages": [
6        {
7            "organizationId": "22222222-2222-4222-8222-222222222222",
8            "sellerOrVendorId": null,
9            "messageId": "44444444-4444-4444-8444-444444444444",
10            "messageType": "PLATFORM_API_KEY_CREATED",
11            "messageSummary": {
12                "schemaVersion": 1,
13                "category": "PLATFORM",
14                "occurredAt": "2026-11-11T10:00:00.000Z",
15                "subjectType": "API_KEY",
16                "subjectId": "55555555-5555-4555-8555-555555555555",
17                "subjectVersion": "1",
18                "correlationId": "66666666-6666-4666-8666-666666666666",
19                "actor": { "type": "USER", "id": "77777777-7777-4777-8777-777777777777" }
20            },
21            "messageData": {
22                "key": {
23                    "keyId": "55555555-5555-4555-8555-555555555555",
24                    "keyType": "API",
25                    "name": "Example automation",
26                    "owner": { "type": "USER", "id": "77777777-7777-4777-8777-777777777777" },
27                    "createdAt": "2026-11-11T10:00:00.000Z",
28                    "expiresAt": "2027-11-11T10:00:00.000Z"
29                }
30            }
31        }
32    ]
33}

webhookId identifies the receiving subscription. For pause or resume events, the subject webhook in messageData can be another subscription.

Account, initial-load, connection, and Action events have the affected account's UUID in sellerOrVendorId. Organization events use null. The subject ID identifies the account, connection, Action, payment failure, subscription, user, key, authorization, or token-balance Organization described by the event.

For example, a synthetic pause payload can contain:

1{
2    "webhook": {
3        "id": "33333333-3333-4333-8333-333333333333",
4        "name": "Example endpoint",
5        "kind": "PLATFORM"
6    },
7    "previousStatus": "ACTIVE",
8    "status": "PAUSED",
9    "reason": "DELIVERY_FAILED",
10    "changedAt": "2026-11-11T10:00:00.000Z",
11    "httpStatusCode": 503
12}

The Platform contracts use explicit allowed fields. They exclude credentials, OAuth codes and tokens, key values and hashes, payment-card details, and buyer information.

Event timing and duplicate handling

Events describe successful completed changes. Their occurredAt records when that change occurred. Initial-load, payment, and asynchronous Action events follow the confirmed state, rather than the start of a request. Arrival is asynchronous and has no global ordering guarantee.

Use messageId to deduplicate messages. It stays the same if a message is delivered again. deliveryId changes for each HTTP attempt. A request accepted by your endpoint can be delivered again if its success could not be recorded, so delivery is not exactly once.

subjectVersion is a decimal integer encoded as a string. It orders snapshots for the same Organization, subject type, and subject ID. Several event types or permission-change parts from one operation can share that version. Process each event type, even when it shares a version with another type. Collect every permission-change part for its changeId before applying that change. Use correlationId to associate events from the same operation.

Pausing, resuming, and delivery limits

A non-2xx response, a timeout after 30 seconds, or a network failure records a failure and pauses that subscription. DataDoe emails the active Organization Admins. Recorded HTTP failures are not automatically retried or replayed. Delivery is not guaranteed while your endpoint is unavailable.

Return a successful 2xx response promptly and process the accepted message separately. Check the secret header before accepting it.

Manual pauses and loss of the execution owner's Admin membership stop future delivery. DataDoe does not send an email when the owner loses Admin membership. Another Admin can choose an active Admin in Run as and resume the subscription. Resuming starts future delivery and does not replay canceled messages.

Pending deliveries are canceled if the subscription is deleted or paused, its target, secret, owner, or delivery settings changes, or the event's message type is removed. Renaming the subscription or adding unrelated message types does not cancel pending events. Delivery logs show the cancellation reason.

A paused webhook cannot receive its own pause notification. Other active Platform subscriptions can receive it. A resumed webhook can receive its resume event if it subscribes to that type. Repeating a command that leaves the status unchanged does not produce another transition event.

Organization deletion stops all deliveries. See Roles and permissions for access management.