Dotdigital Webhooks

generated: '2026-08-13'
method: searched
source: >-
  https://marketing.developer.dotdigital.com/reference/webhooks,
  https://marketing.developer.dotdigital.com/reference/message-events,
  https://marketing.developer.dotdigital.com/reference/profile-events,
  https://marketing.developer.dotdigital.com/reference/chat-events,
  openapi/dotdigital-webhook-openapi.yml, openapi/dotdigital-events-openapi.yml,
  openapi/dotdigital-data-firehose-openapi.yml
spec_type: none
asyncapi_published: false
description: >-
  Dotdigital has a substantial, well-documented event surface across three distinct mechanisms —
  outbound webhooks (CPaaS), an Events in/out API with durable subscriptions, and Data Firehose
  batch streaming to cloud storage — but publishes NO AsyncAPI document for any of them. This
  artifact captures the webhook contract so the event surface is machine-readable somewhere.
  Probes for /asyncapi.yaml and /asyncapi.json on the developer and API hosts returned 404.
mechanisms:
  - name: Webhooks
    kind: push
    management_api: openapi/dotdigital-webhook-openapi.yml
    docs: https://marketing.developer.dotdigital.com/reference/webhooks
    discovery_operations:
      - 'GET /cpaas/webhooks/availableevents  — retrieves the available webhook event types'
      - 'GET /cpaas/webhooks/availabletemplates — retrieves the event payload templates'
    note: >-
      The authoritative event-type list is served by the API itself (availableevents), which is
      account-scoped and therefore requires credentials to enumerate. The event families below
      are read from the public documentation.
  - name: Events API (in/out)
    kind: pull with durable subscription
    management_api: openapi/dotdigital-events-openapi.yml
    docs: https://marketing.developer.dotdigital.com/reference/events-overview
    note: >-
      Create a subscription with filters (filters are ANDed; repeat the event type to OR), then
      poll exportEvents with a checkPoint cursor. A subscription not read within 30 days is
      automatically set inactive. Large payload fields are fetched separately via retrieveLob.
  - name: Data Firehose
    kind: batch stream to cloud storage
    management_api: openapi/dotdigital-data-firehose-openapi.yml
    docs: https://marketing.developer.dotdigital.com/docs/dotdigital-data-firehose-developer-reference
    targets: [Amazon S3, Azure Blob Storage, FTPS, SFTP, Google Cloud Storage]
    status: private preview
    note: The spec's own description says it is in private preview and should not be used.
transport:
  protocol: HTTPS POST to a caller-supplied URL
  content_type: application/json
  batching:
    supported: true
    recommended: true
    max_events_per_batch: 500
    min_events_per_batch: 1
    batch_timeout_seconds: {min: 1, max: 60}
    shape: JSON array of envelopes
  receiver_response_contract:
    - {status: '200/201/2xx', meaning: Data accepted}
    - {status: 400, meaning: Could not process the data sent — this will NOT be retried}
    - {status: 401, meaning: Sender authentication failed or HMAC not valid}
    - {status: other, meaning: Failed to accept — will be retried}
  receiver_timeout_seconds: 10
security:
  signing: HMAC
  algorithm: SHA-1
  header: X-Comapi-Signature
  encoding: hex (NOT base64 — the docs call this out explicitly)
  computed_over: the raw HTTP body, UTF-8
  secret: caller-configured on the webhook registration
  secret_guidance: at least 16 characters, 36 or more recommended
  note: >-
    A mismatch must be answered with HTTP 401. The header name retains the `Comapi` prefix from
    the acquired platform, which is a discoverability trap for anyone searching for
    "X-Dotdigital-Signature".
delivery:
  retry: exponential-ish fixed backoff schedule
  max_retry_window_hours: 24
  drop_after_window: true
  schedule_seconds: [5, 10, 30, 60, 120, 300, 600, 900, 1800, 3600, 7200, 14400, 14400, 14400, 14400, 14400]
envelope:
  fields:
    - {name: eventId, type: string, required: true, description: Unique identifier for this event}
    - {name: accountId, type: integer, required: true, description: The account the event belongs to}
    - {name: apiSpaceId, type: string, required: true, description: The API Space the event came from}
    - {name: name, type: string, required: true, description: The event type name, e.g. message.sent}
    - {name: payload, type: object, required: true, description: Event-type-specific body}
    - {name: revision, type: integer, required: true, description: Increments with each event for the entity}
    - {name: etag, type: string, required: true, description: HTTP ETag entity hash for change detection}
    - {name: timestamp, type: string, format: date-time, required: true, description: UTC ISO 8601 time the event occurred}
  routing_field: name
  note: One registration can carry many event types; dispatch on `name`.
event_families:
  - family: message
    docs: https://marketing.developer.dotdigital.com/reference/message-events
    events:
      - {name: message.sent, description: Message has been sent on the channel}
      - {name: message.sentRequest, description: Send request accepted for the channel}
      - {name: message.delivered, description: Message delivered}
      - {name: message.read, description: Message read/opened, on channels that support it}
      - {name: message.expired, description: Not delivered within expiresOn or the channel default window}
      - {name: message.failed, description: Message failed to be delivered}
  - family: interaction
    events:
      - {name: interaction.click, description: 'Trackable link clicked; supported on transactional email links and shortened SMS links'}
  - family: profile
    docs: https://marketing.developer.dotdigital.com/reference/profile-events
    scope: Omnichannel API profiles (not Marketing contacts)
    events:
      - {name: profile.create}
      - {name: profile.update}
      - {name: profile.delete}
      - {name: profile.undelete}
      - {name: profile.devicesUpdated, description: Devices associated with a profile changed}
  - family: chat
    docs: https://marketing.developer.dotdigital.com/reference/chat-events
    events:
      - {name: chat.create}
      - {name: chat.channelUpdated, description: Chat switched channel, e.g. web chat to email}
      - {name: chat.closed}
      - {name: chat.delete}
  - family: app-messaging conversation
    docs: https://marketing.developer.dotdigital.com/reference/app-messaging-conversation-events
  - family: app-messaging message
    docs: https://marketing.developer.dotdigital.com/reference/app-messaging-message-events
  - family: app-messaging session
    docs: https://marketing.developer.dotdigital.com/reference/app-messaging-session-events
  - family: chat message
    docs: https://marketing.developer.dotdigital.com/reference/chat-message-events
  - family: chat presence
    docs: https://marketing.developer.dotdigital.com/reference/chat-presence-events
  - family: facebook
    docs: https://marketing.developer.dotdigital.com/reference/facebook-events
correlation:
  mechanism: metadata echo
  note: >-
    Values passed in the `metadata` facility on a send are included on the resulting webhook
    events; the docs recommend this for reconciling receipts back to sends.
gaps:
  - No AsyncAPI (or CloudEvents) document for any of the three mechanisms.
  - >-
    HMAC-SHA1 is the only signing option; SHA-256 is not offered, and the signature is not
    timestamped, so replay protection is left to the receiver.
  - >-
    The complete event-type list is only obtainable from an authenticated call to
    GET /cpaas/webhooks/availableevents; there is no public enumeration.