Didomi - Developers documentation
  • Introduction
  • SDKs
    • Introduction
    • Web SDK
      • Getting started
      • Tags and vendors management
        • Tags management
          • Events & Variables
            • Deprecated
            • Custom events
          • Tag managers
            • Adobe Launch/DTM
            • Eulerian
            • Google Tag Manager
              • Configure the Didomi / GTM integration
              • Didomi's GTM template
            • Tealium
            • Other tag managers
        • Custom Didomi <script> tags
        • Third-party integrations
          • Google Ad Manager / AdSense
            • GDPR via Non-Personalized Ads
              • Share consent and load/refresh ads
              • Share consent without loading or refreshing ads
            • US states laws
          • Google Consent Mode V2
          • Kameleoon
          • Piano Analytics (AT Internet)
          • Prebid
            • GDPR via IAB TCF
            • US states laws
          • Salesforce DMP (Krux)
        • IAB frameworks
        • Programmatic API
      • Configuration
        • Bots (SEO & Performance tools)
        • Configuration by URL
        • Cookies and storage
        • Custom domains for events
        • Notice
          • Behavior
          • Interactions
          • Look and feel
        • Preferences
        • Theme
      • AB tests
      • Custom domain
        • Domain delegation
        • Reverse proxy
      • Share consents between domains
      • Share consents across devices
      • Pass user choices in query string
      • Serve Didomi assets from your domain
      • Reference
        • API
          • Deprecated
        • Events
      • Performance
      • Versions
    • Mobile and TV SDKs
      • Android and Android TV
        • Setup
        • Logging
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • iOS and tvOS
        • Setup
        • Logging
        • App Tracking Transparency (iOS 14.5+)
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • Unity
        • Setup
        • Reference
        • Versions
        • Troubleshooting
      • React Native
        • Setup
        • Reference
          • Deprecated
        • Versions
      • Flutter
        • Setup
        • Reference
        • Versions
      • Consent notice
        • Getting started
        • Customize the notice
        • Customize the preferences popup
        • Customize the theme & UI
        • Load notice by ID
      • Third-party SDKs
      • Share consents across devices
      • Share consent with WebViews
      • Google Consent Mode v2
      • FAQ
    • AMP SDK
      • Blocking Behaviors
        • Load immediately on page load
        • Load only after consent (positive or negative)
        • Load only after positive consent
      • Consent status for vendors
    • Help & Support
  • API
    • Introduction
      • Authentication
      • Errors
      • Pagination
      • Filters
      • Caching
      • Rate limiting
      • Quotas
      • Translations
    • Data Manager
      • Regulations
      • Configuration Tree
      • Purposes
        • Purposes & Vendors Numerical IDs
      • Preferences Library
      • User Rights
    • Widgets
      • Consent notices
        • Notices
        • Configurations
        • Multi-Regulation Configurations
          • Migration of Existing Notices and API Updates
        • Deployments
        • Tutorials
          • Create and publish a consent notice
          • Create and publish a multi-regulation consent notice
      • Privacy widgets
        • Create a widget
        • Retrieve widgets
        • Edit a widget
          • Content & Design
            • Themes & Shapes
            • Components
              • auth
              • dsar_form
              • footer
              • header
              • preference
              • preference_value
              • save
              • section
              • sections
            • Options
          • Purposes & preferences
          • Settings
        • Deploy a Widget
          • Use your own subdomain
          • Use your own domain
          • Implement an embeddable widget on your website
        • Authentication
          • Manage authentication providers
          • Authenticate your end-user
        • Archive a widget
        • Headless widgets
          • Public Methods
          • Custom elements
          • Custom events
          • Event listeners
        • Tutorial
          • Launch a Preference Center from a mobile app
    • Compliance Reports
      • Properties
      • Reports
      • CSV format reference
      • Websites
    • Consents and Preferences
      • Events
        • Generate IAB TCF consent string
      • Links
      • Proofs
      • Tokens
      • Secrets
      • Users
      • Tutorial
        • Collect and operate data
    • Privacy Requests
      • Requests
      • Notes
      • Links
      • Emails
  • Integrations
    • Introduction
      • Quotas
    • Generic integrations
      • Batch export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
        • Exported data
          • Notices consents
        • Logs
      • Webhooks
      • Batch import
      • Analytics export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
    • Third-party apps
      • CMP integrations
        • Didomi-mParticle integration for your CMP
        • Deploy Didomi’s SDK for your Adobe Commerce website
      • Preference Management Platform integrations
        • Actito
        • Adobe Campaign Classic
        • Adobe Experience Cloud
        • Adobe Marketo Engage
        • Adobe Source Connector
        • Braze
        • Dotdigital
        • Hubspot
        • Mailchimp
        • Microsoft Dynamics 365
        • Salesforce Marketing Cloud
        • Salesforce Sales & Service Cloud
        • Selligent
        • Brevo (ex Sendinblue)
    • Tutorials
      • Configure a HTTP webhook
      • Configure a batch export
      • Configure an analytics export
    • Emailing
      • Configurations
        • Actito Email
        • Actito SMS
        • Adobe Campaign Classic
        • Adobe Campaign Standard
      • Emails
        • Templates
        • Manage your templates
Powered by GitBook
On this page
  • Configuration
  • Authentication
  • Payload
  • Events
  • Filters
  • Flatten request body
  • Pending events
  1. Integrations
  2. Generic integrations

Webhooks

PreviousLogsNextBatch import

Last updated 1 month ago

Webhooks allow you to subscribe to events happening on the Didomi platform to implement custom workflows when your users change their consent preferences. When users make choices on your websites, mobile apps, or preferences center, you will receive a notification allowing you to react to user choices.

When an event is triggered, we'll send a HTTP POST payload to the configured webhook endpoint. Webhooks are configured at the organization level and automatically apply to all consent events triggered within your organization, on all websites, mobile apps, or preferences center.

The Webhooks are not yet compatible with a multi-regulation approach. At this moment in time, user consent will be associated with GDPR in the events that you receive.

Configuration

Webhooks can be configured from the Didomi Marketplace. Once enabled, go to the Manage sub-section under the Marketplace to configure your webhook.

Alternatively, you can reach out to our support team if you need further assistance. Provide the endpoint to send events to and, optionally, the OAuth credentials (client ID and client secret) to use.

To ensure that the consent events are received, when your endpoint is down, we retry at least five times during five minutes before moving on.

After the maximum amount of retries is reached, the event is placed in a permanent storage for later processing.

Authentication

OAuth Access Token

The Didomi servers will authenticate against your OAuth authorization server with a Client ID and a Client Secret that you provide to obtain an Access Token.

Didomi will then call your API endpoint for sending emails with the Access Token provided in the Authorization header as a Bearer token.

IP address

API calls from Didomi will originate from the IP 35.159.1.63 . You must whitelist that IP to allow traffic from it for emails to be sent.

Payload

Events sent to your HTTP endpoints are sent as JSON-encoded objects with the following information:

Field
Description
type

Event type

The type of event.

string

Parameters

Entities affected by the event.

object

Events

Type

Description

Parameters

event.created

A new consent event has been created

event.updated

An existing consent event has been updated

  • source

event.deleted

An existing consent event has been deleted

user.created

A new user has been created

user.updated

An existing user has been updated

user.deleted

An existing user has been deleted

The payload is a JSON string in the body of the HTTP request. Examples:

{
  "type": "user.updated",
  "parameters": {
    "source": {
      "id": "unique_event_id",
      "created_at": "2019-08-07T10:45:11Z",
      ...
    },
    "old_entity": {
      "id": "didomi_user_id",
      "organization_user_id": "organization_user_id",
      ...
    },
    "new_entity": {
      "id": "didomi_user_id",
      "organization_user_id": "organization_user_id",
      ...  
    }
  }
}
{
  "type": "event.deleted",
  "parameters": {
    "entity": {
      "id": "deleted_event_id",
      "created_at": "2019-08-07T10:45:11Z",
      ...
    },
  }
}

Filters

You can customize which events your webhook will receive by selecting the desired event types in the Didomi Marketplace. If no event types are selected, the webhook will receive all available events by default.

Flatten request body

By enabling this option in the interface, your webhook payload will be transformed into a flat JSON object, simplifying property mapping depending on your webhook use case. Flattening converts a JSON object into a flat key-value format, where each key represents a property in the original JSON using a double underscore (__) as a separator. Currently, only the entity and new_entity properties are flattened, merging into a single entity property for simplicity.

Example

// event.created (original)
{
  "type": "event.created",
  "parameters": {
    "entity": {
      "organization_id": "didomi",
      "user": {
        "id": "some_unique_id",
        "organization_user_id": "example@didomi.io"
      },
      "consents": {
        "purposes": [
          {
            "id": "geo_location",
            "enabled": true
          },
          {
            "id": "market_research",
            "enabled": true
          }
        ]
      }
    }
  }
}
// event.created (Flattened)
{
  "type": "event.created",
  "parameters__entity__organization_id": "didomi",
  "parameters__entity__user__id": "some_unique_id",
  "parameters__entity__user__organization_user_id": "example@didomi.io",
  "parameters__entity__consents__purposes__geolocation_data__enabled": true,
  "parameters__entity__consents__purposes__market_research__enabled": true
}

Pending events

Pending events (with status pending_approval or similar) are always sent as event.created webhooks.

However, new pending events only generate user.created events if a new user is created as a result of a pending event. If a pending event applies to an existing user, a user.updated event is not generated as the user is not effectively modified until the event becomes confirmed.

When a pending event becomes confirmed and, assuming it contains changes that effectively modify the status of the user, then and only then a user.updated event is sent.

Requests sent to your API endpoint can be authenticated via .

entity: Created

old_entity: before it gets updated

new_entity: after the update

entity: Deleted

entity: Created

source: Event that triggered the update (if any)

old_entity: before it gets updated

new_entity: after the update

entity: Deleted

OAuth Client Credentials grant
Didomi Marketplace
User
User
User
User
User
Event
Event
Event
Event