The Webhooks feature enables real-time synchronization between Acquia DAM (Widen) assets and Drupal media entities. The feature sends immediate notifications to your Drupal application when assets are updated, deleted, or released. This process keeps content synchronized without waiting for cron to run.
Prerequisites
In your Drupal application:
Confirm that Acquia DAM (Widen) module version 1.1.17 or later is enabled.
Confirm that you have the Administer Acquia DAM permission.
Confirm that your Drupal application is accessible through a publicly reachable HTTPS URL.
Confirm that the Acquia DAM Webhooks submodule is enabled. To enable the submodule:
In the administrative menu, select Extend.
Search for Acquia DAM Webhooks.
Select the checkbox for the submodule.
Select Install.
Alternatively, run the following Drush command to enable the submodule:
drush en acquia_dam_webhooks
Access the Webhooks configuration page.
Configure webhook settings
In the administrative menu, select Configuration.
Under Media, select Acquia DAM.
Select the Webhooks tab.
Select the Enable webhook management checkbox. This setting enables automatic webhook health checks in Drupal. The checks run through cron according to the frequency configured in step 5. This setting does not register webhooks or control event delivery by itself.
Select a value for Webhook health check frequency. During each scheduled cron run, Drupal verifies the webhook registrations against Acquia DAM (Widen) and registers any missing or stale configurations.
Verify that the Webhook delivery URL is correct.
Select the webhook events that you want to register.
Note
Start with the essential webhook events. Acquia DAM (Widen) limits each account to 10 webhook registrations. Omit optional event types to help prevent the account from reaching this limit. Register webhooks only in production environments when possible. Every environment that registers webhooks consumes a slot from the shared account limit. Registering webhooks in development, staging, or preview environments reduces the number of slots available to production.Lower environments can remain synchronized with changes through cron polling without registering their own webhooks.
Manage webhooks through the command line
Site administrators can use Drush commands to manage webhook registrations, automate deployments, and test connectivity.
Webhook register
Register webhook configurations with Acquia DAM (Widen) for selected event types. The command uses a find-and-claim strategy that reuses existing webhook configurations before it creates new ones. This strategy helps prevent the shared DAM account from reaching the 10-configuration limit.
Command syntax:
drush acquia-dam:webhook-register
Options:
--force: Registers the webhook again even when a webhook ID is already stored for the event type.
--essential: Registers only the three essential event types: asset_deleted, asset_metadata_value_updated, and asset_version_added.
--all: Registers all event types: asset_deleted, asset_expiration_date_updated, asset_metadata_value_updated, asset_release_date_updated, asset_version_added, and asset_created.
--type: Specifies a comma-separated list of event types to register. This option overrides the default configuration. For example, --type=asset_deleted,asset_version_added.
Examples:
drush acquia-dam:webhook-register --essential
drush acquia-dam:webhook-register --force
drush acquia-dam:webhook-register --type=asset_deleted,asset_version_added
Webhook sync
Reconcile the webhook IDs stored in Drupal with the webhook registrations in Acquia DAM (Widen). If a stored webhook is missing or stale in Acquia DAM, Drupal registers it again.
Run this command periodically or after a suspected webhook issue. For example, run it after a webhook is manually deleted in the Acquia DAM (Widen) user interface.
Command syntax:
drush acquia-dam:webhook-sync
For each configured event type, the command reports one of the following statuses:
OK: The stored webhook is present in Acquia DAM.
Re-registered: The webhook was not present or stale, and was registered again.
FAILED: Registration failed. Check the Drupal log for details.
Webhook ping
Send a ping request to every registered webhook configuration. Use this command to verify that Acquia DAM can reach your Drupal application through the delivery URL.
Run this command after a domain change, firewall update, or CDN deployment.
Command syntax:
drush acquia-dam:webhook-ping
Note
If no webhooks are registered, the command reports the status and exits without contacting the DAM API. Register the webhooks and then run the command: drush acquia-dam:webhook-register
Webhook status
Display the current webhook registration status without making an API call to Acquia DAM. This command provides a read-only view of the webhook data stored locally.
The command displays the delivery URL registered for your site, the webhook configuration ID for each event type, and the registration status.
Command syntax:
drush acquia-dam:webhook-status
The command reports one of the following statuses:
Registered
Not registered
Webhook deregister
Remove all registered webhook configurations from Acquia DAM. The command also clears the stored webhook IDs and secrets from Drupal state.
Run this command before you decommission a site or reset the webhook configuration.
Command syntax:
drush acquia-dam:webhook-deregister
Note
If no webhooks are registered, the command reports the status and exits without contacting the DAM API.
Run this command when you need to remove registrations from an environment before copying its database to another environment.
Automatic credential rotation
When you update your Acquia DAM credentials in the main Acquia DAM configuration form, the Webhooks submodule automatically completes the following actions:
Deregisters the existing webhook configurations with the old credentials.
Saves the new credentials.
Registers the webhook configurations with the new credentials.
No manual action is required.
Automatic health-check synchronization
When Enable webhook management is selected, cron performs a registration health check at the configured frequency. The default frequency is once per day.
The health check reconciles the webhook IDs stored locally with the configurations registered in Acquia DAM. Drupal registers any missing webhook configurations again.
Deregistration when disabling or uninstalling the submodule
Disable or uninstall the Acquia DAM Webhooks submodule to automatically deregister all webhook configurations from Acquia DAM. This action also removes the stored registration IDs and secrets from your Drupal application.
Environment database copies and deregistration
When you copy a database from one environment to another, the source environment’s webhook registration IDs are copied to the target environment.
For example, when you copy the production database to staging, the staging environment receives the production webhook registration IDs. Run the following command on the target environment after copying the database:
drush acquia-dam:webhook-register --force
This command replaces the copied registration IDs with registrations that use the target environment’s delivery URL.
Important notes
Acquia DAM enforces a maximum of 10 webhook configurations per account.
Environments that share a DAM account can overwrite one another’s webhook registrations.
Local development environments, such as localhost, cannot be reached by Acquia DAM webhooks.
Signature validation requires the raw request body to reach Drupal without modification by a proxy or CDN.
Webhook events
Acquia DAM (Widen) supports webhook event types that notify your Drupal application when assets change.
The three essential events directly affect content that already exists in Drupal. Drupal processes these events synchronously within the HTTP request.
The two optional date events are also processed synchronously when enabled. When these events are disabled, the parent module applies the corresponding changes through cron polling.
The optional asset_created event is processed through the background queue.
Asset deleted
Acquia DAM (Widen) sends this event when an asset is permanently deleted.
The Drupal application immediately unpublishes every media entity that references the deleted asset. Each unpublished entity receives a new revision with an automatic log message that records the reason for unpublishing.
Triggered by: Permanent deletion of an asset in Acquia DAM.
Drupal action: Unpublishes every media entity that references the asset. Drupal saves a new revision for each entity with the following log message: Automatically unpublished via webhook: the associated DAM asset was deleted.
Processing model: Inline. Drupal processes the event synchronously within the HTTP request. No cron run is required.
Registration: Essential. The event is included in Register essential webhooks.
Asset metadata value updated
Acquia DAM (Widen) sends this event when one or more metadata fields on an asset change.
The Drupal application immediately updates each media entity that references the asset and synchronizes the mapped metadata fields.
Triggered by: A change to one or more metadata fields on an asset.
Drupal action: Updates each media entity that references the asset. Drupal saves a new revision that reflects the current metadata.
Processing model: Inline. Drupal processes the event synchronously within the HTTP request.
Registration: Essential.
The update uses the same logic as the cron-based synchronization path. This provides consistent results regardless of which process handles the change.
Asset version added
Acquia DAM (Widen) sends this event when a new file version is uploaded to an existing asset.
The Drupal application immediately updates each media entity that references the asset to use the latest version.
Triggered by: Upload of a new file version to an existing asset.
Drupal action: Updates each media entity that references the asset to use the new version. Drupal saves a new revision for each entity.
Processing model: Inline. Drupal processes the event synchronously within the HTTP request.
Registration: Essential.
File downloads are refreshed when the Download and sync assets option is enabled for the relevant media type.
Asset expiration date updated
Acquia DAM (Widen) sends this event when the expiration date of an asset changes.
The Drupal application immediately resynchronizes each media entity that references the asset. If the asset expires, Drupal unpublishes the related media.
When this event is disabled, the parent module applies expiration changes through cron polling.
Triggered by: A change to the expiration date of an asset.
Drupal action: Updates the media entity that references the asset. Drupal updates the expiration date field and publishes or unpublishes the entity to match the current asset availability.
Processing model: Inline when enabled. Cron polling processes the change when the event is disabled.
Registration: Optional.
Asset release date updated
Acquia DAM (Widen) sends this event when the release date of an asset changes.
The Drupal application immediately resynchronizes each media entity that references the asset. If the asset expires, Drupal unpublishes the related media. If the release date is in the future, Drupal unpublishes the entity.
When this event is disabled, the parent module applies release date changes through cron polling.
Triggered by: A change to the release date of an asset.
Drupal action: Updates the media entity that references the asset. Drupal publishes or unpublishes the entity to match the current asset availability.
Processing model: Inline when enabled. Cron polling processes the change when the event is disabled.
Registration: Optional.
Asset created
Acquia DAM (Widen) sends this event when a new asset is uploaded for the first time.
Because this event is triggered for every new upload in the Acquia DAM account, it requires explicit opt-in and configuration. The configuration determines which assets automatically create Drupal media entities.
Prioritize the Acquia DAM Bulk Asset Import feature over the asset_created webhook event when importing multiple assets.
Triggered by: Upload of a new asset to Acquia DAM.
Drupal action: Creates a Drupal media entity according to the configuration in the Webhooks settings form:
When Allow all asset processing is selected, every asset_created event creates a new Drupal media entity that uses the appropriate media type.
When asset group filtering is configured, only assets that belong to the configured DAM asset groups create media entities. You can also configure media type restrictions for each group.
When no asset group filtering is configured, Drupal logs the event but does not create a media entity.
Processing model: Queued. Drupal places the event in the acquia_dam_webhook_asset_create queue. The queue is processed during the next cron run or through a manual queue run.
Registration: Optional. The event requires explicit opt-in through the Webhooks settings form.
Webhook event notes
Drupal processes the three essential events within the HTTP request from Acquia DAM. The Drupal application reflects the change within seconds, regardless of the cron frequency.
The asset expiration date updated and asset release date updated events are optional. When enabled, Drupal processes these events inline. When disabled, the parent module applies the changes through cron polling. Enable these events when you require availability changes to occur before the next scheduled cron run.
Cron remains necessary when webhooks are enabled. Cron handles scenarios that webhooks do not cover and provides a safety net for failed or retried webhook deliveries.
The cron-based synchronization path and the webhook path use the same logic through the shared AssetMediaSyncService. A media entity updated by a webhook and the same entity updated by cron produce the same result.
The asset_created event adds a queue item for every new upload in the Acquia DAM account. Configure either Allow all asset processing or specific asset group filtering to enable automatic media creation. Without this configuration, Drupal logs the event but does not create a media entity.
How do I use the webhooks feature in the Acquia DAM Drupal module?
The Webhooks feature enables real-time synchronization between Acquia DAM (Widen) assets and Drupal media entities. The feature sends immediate notifications to your Drupal application when assets are updated, deleted, or released. This process keeps content synchronized without waiting for cron to run.
Prerequisites
In your Drupal application:
Confirm that Acquia DAM (Widen) module version 1.1.17 or later is enabled.
Confirm that you have the Administer Acquia DAM permission.
Confirm that your Drupal application is accessible through a publicly reachable HTTPS URL.
Confirm that the Acquia DAM Webhooks submodule is enabled. To enable the submodule:
In the administrative menu, select Extend.
Search for Acquia DAM Webhooks.
Select the checkbox for the submodule.
Select Install.
Alternatively, run the following Drush command to enable the submodule:
drush en acquia_dam_webhooks
Access the Webhooks configuration page.
Configure webhook settings
In the administrative menu, select Configuration.
Under Media, select Acquia DAM.
Select the Webhooks tab.
Select the Enable webhook management checkbox. This setting enables automatic webhook health checks in Drupal. The checks run through cron according to the frequency configured in step 5. This setting does not register webhooks or control event delivery by itself.
Select a value for Webhook health check frequency. During each scheduled cron run, Drupal verifies the webhook registrations against Acquia DAM (Widen) and registers any missing or stale configurations.
Verify that the Webhook delivery URL is correct.
Select the webhook events that you want to register.
Note
Start with the essential webhook events. Acquia DAM (Widen) limits each account to 10 webhook registrations. Omit optional event types to help prevent the account from reaching this limit. Register webhooks only in production environments when possible. Every environment that registers webhooks consumes a slot from the shared account limit. Registering webhooks in development, staging, or preview environments reduces the number of slots available to production.Lower environments can remain synchronized with changes through cron polling without registering their own webhooks.
Manage webhooks through the command line
Site administrators can use Drush commands to manage webhook registrations, automate deployments, and test connectivity.
Webhook register
Register webhook configurations with Acquia DAM (Widen) for selected event types. The command uses a find-and-claim strategy that reuses existing webhook configurations before it creates new ones. This strategy helps prevent the shared DAM account from reaching the 10-configuration limit.
Command syntax:
drush acquia-dam:webhook-register
Options:
--force: Registers the webhook again even when a webhook ID is already stored for the event type.
--essential: Registers only the three essential event types: asset_deleted, asset_metadata_value_updated, and asset_version_added.
--all: Registers all event types: asset_deleted, asset_expiration_date_updated, asset_metadata_value_updated, asset_release_date_updated, asset_version_added, and asset_created.
--type: Specifies a comma-separated list of event types to register. This option overrides the default configuration. For example, --type=asset_deleted,asset_version_added.
Examples:
drush acquia-dam:webhook-register --essential
drush acquia-dam:webhook-register --force
drush acquia-dam:webhook-register --type=asset_deleted,asset_version_added
Webhook sync
Reconcile the webhook IDs stored in Drupal with the webhook registrations in Acquia DAM (Widen). If a stored webhook is missing or stale in Acquia DAM, Drupal registers it again.
Run this command periodically or after a suspected webhook issue. For example, run it after a webhook is manually deleted in the Acquia DAM (Widen) user interface.
Command syntax:
drush acquia-dam:webhook-sync
For each configured event type, the command reports one of the following statuses:
OK: The stored webhook is present in Acquia DAM.
Re-registered: The webhook was not present or stale, and was registered again.
FAILED: Registration failed. Check the Drupal log for details.
Webhook ping
Send a ping request to every registered webhook configuration. Use this command to verify that Acquia DAM can reach your Drupal application through the delivery URL.
Run this command after a domain change, firewall update, or CDN deployment.
Command syntax:
drush acquia-dam:webhook-ping
Note
If no webhooks are registered, the command reports the status and exits without contacting the DAM API. Register the webhooks and then run the command: drush acquia-dam:webhook-register
Webhook status
Display the current webhook registration status without making an API call to Acquia DAM. This command provides a read-only view of the webhook data stored locally.
The command displays the delivery URL registered for your site, the webhook configuration ID for each event type, and the registration status.
Command syntax:
drush acquia-dam:webhook-status
The command reports one of the following statuses:
Registered
Not registered
Webhook deregister
Remove all registered webhook configurations from Acquia DAM. The command also clears the stored webhook IDs and secrets from Drupal state.
Run this command before you decommission a site or reset the webhook configuration.
Command syntax:
drush acquia-dam:webhook-deregister
Note
If no webhooks are registered, the command reports the status and exits without contacting the DAM API.
Run this command when you need to remove registrations from an environment before copying its database to another environment.
Automatic credential rotation
When you update your Acquia DAM credentials in the main Acquia DAM configuration form, the Webhooks submodule automatically completes the following actions:
Deregisters the existing webhook configurations with the old credentials.
Saves the new credentials.
Registers the webhook configurations with the new credentials.
No manual action is required.
Automatic health-check synchronization
When Enable webhook management is selected, cron performs a registration health check at the configured frequency. The default frequency is once per day.
The health check reconciles the webhook IDs stored locally with the configurations registered in Acquia DAM. Drupal registers any missing webhook configurations again.
Deregistration when disabling or uninstalling the submodule
Disable or uninstall the Acquia DAM Webhooks submodule to automatically deregister all webhook configurations from Acquia DAM. This action also removes the stored registration IDs and secrets from your Drupal application.
Environment database copies and deregistration
When you copy a database from one environment to another, the source environment’s webhook registration IDs are copied to the target environment.
For example, when you copy the production database to staging, the staging environment receives the production webhook registration IDs. Run the following command on the target environment after copying the database:
drush acquia-dam:webhook-register --force
This command replaces the copied registration IDs with registrations that use the target environment’s delivery URL.
Important notes
Acquia DAM enforces a maximum of 10 webhook configurations per account.
Environments that share a DAM account can overwrite one another’s webhook registrations.
Local development environments, such as localhost, cannot be reached by Acquia DAM webhooks.
Signature validation requires the raw request body to reach Drupal without modification by a proxy or CDN.
Webhook events
Acquia DAM (Widen) supports webhook event types that notify your Drupal application when assets change.
The three essential events directly affect content that already exists in Drupal. Drupal processes these events synchronously within the HTTP request.
The two optional date events are also processed synchronously when enabled. When these events are disabled, the parent module applies the corresponding changes through cron polling.
The optional asset_created event is processed through the background queue.
Asset deleted
Acquia DAM (Widen) sends this event when an asset is permanently deleted.
The Drupal application immediately unpublishes every media entity that references the deleted asset. Each unpublished entity receives a new revision with an automatic log message that records the reason for unpublishing.
Triggered by: Permanent deletion of an asset in Acquia DAM.
Drupal action: Unpublishes every media entity that references the asset. Drupal saves a new revision for each entity with the following log message: Automatically unpublished via webhook: the associated DAM asset was deleted.
Processing model: Inline. Drupal processes the event synchronously within the HTTP request. No cron run is required.
Registration: Essential. The event is included in Register essential webhooks.
Asset metadata value updated
Acquia DAM (Widen) sends this event when one or more metadata fields on an asset change.
The Drupal application immediately updates each media entity that references the asset and synchronizes the mapped metadata fields.
Triggered by: A change to one or more metadata fields on an asset.
Drupal action: Updates each media entity that references the asset. Drupal saves a new revision that reflects the current metadata.
Processing model: Inline. Drupal processes the event synchronously within the HTTP request.
Registration: Essential.
The update uses the same logic as the cron-based synchronization path. This provides consistent results regardless of which process handles the change.
Asset version added
Acquia DAM (Widen) sends this event when a new file version is uploaded to an existing asset.
The Drupal application immediately updates each media entity that references the asset to use the latest version.
Triggered by: Upload of a new file version to an existing asset.
Drupal action: Updates each media entity that references the asset to use the new version. Drupal saves a new revision for each entity.
Processing model: Inline. Drupal processes the event synchronously within the HTTP request.
Registration: Essential.
File downloads are refreshed when the Download and sync assets option is enabled for the relevant media type.
Asset expiration date updated
Acquia DAM (Widen) sends this event when the expiration date of an asset changes.
The Drupal application immediately resynchronizes each media entity that references the asset. If the asset expires, Drupal unpublishes the related media.
When this event is disabled, the parent module applies expiration changes through cron polling.
Triggered by: A change to the expiration date of an asset.
Drupal action: Updates the media entity that references the asset. Drupal updates the expiration date field and publishes or unpublishes the entity to match the current asset availability.
Processing model: Inline when enabled. Cron polling processes the change when the event is disabled.
Registration: Optional.
Asset release date updated
Acquia DAM (Widen) sends this event when the release date of an asset changes.
The Drupal application immediately resynchronizes each media entity that references the asset. If the asset expires, Drupal unpublishes the related media. If the release date is in the future, Drupal unpublishes the entity.
When this event is disabled, the parent module applies release date changes through cron polling.
Triggered by: A change to the release date of an asset.
Drupal action: Updates the media entity that references the asset. Drupal publishes or unpublishes the entity to match the current asset availability.
Processing model: Inline when enabled. Cron polling processes the change when the event is disabled.
Registration: Optional.
Asset created
Acquia DAM (Widen) sends this event when a new asset is uploaded for the first time.
Because this event is triggered for every new upload in the Acquia DAM account, it requires explicit opt-in and configuration. The configuration determines which assets automatically create Drupal media entities.
Prioritize the Acquia DAM Bulk Asset Import feature over the asset_created webhook event when importing multiple assets.
Triggered by: Upload of a new asset to Acquia DAM.
Drupal action: Creates a Drupal media entity according to the configuration in the Webhooks settings form:
When Allow all asset processing is selected, every asset_created event creates a new Drupal media entity that uses the appropriate media type.
When asset group filtering is configured, only assets that belong to the configured DAM asset groups create media entities. You can also configure media type restrictions for each group.
When no asset group filtering is configured, Drupal logs the event but does not create a media entity.
Processing model: Queued. Drupal places the event in the acquia_dam_webhook_asset_create queue. The queue is processed during the next cron run or through a manual queue run.
Registration: Optional. The event requires explicit opt-in through the Webhooks settings form.
Webhook event notes
Drupal processes the three essential events within the HTTP request from Acquia DAM. The Drupal application reflects the change within seconds, regardless of the cron frequency.
The asset expiration date updated and asset release date updated events are optional. When enabled, Drupal processes these events inline. When disabled, the parent module applies the changes through cron polling. Enable these events when you require availability changes to occur before the next scheduled cron run.
Cron remains necessary when webhooks are enabled. Cron handles scenarios that webhooks do not cover and provides a safety net for failed or retried webhook deliveries.
The cron-based synchronization path and the webhook path use the same logic through the shared AssetMediaSyncService. A media entity updated by a webhook and the same entity updated by cron produce the same result.
The asset_created event adds a queue item for every new upload in the Acquia DAM account. Configure either Allow all asset processing or specific asset group filtering to enable automatic media creation. Without this configuration, Drupal logs the event but does not create a media entity.
Acquia DAM (Widen)
If you selected Asset created, configure automatic media creation. To create a Drupal media entity for every new DAM upload, select Allow all asset processing. This setting applies to every new upload in your Acquia DAM account. Use this setting with caution. For more controlled processing, leave Allow all asset processing unselected and configure specific DAM asset groups:
Select Add asset group.
Select a DAM asset group from the list.
To restrict automatic media creation to specific media bundle types, select Filter assets by media type and select one or more media types.
Add additional asset group rows as needed.
If you do not select any media types, Drupal allows all Acquia DAM (Widen) media types for the selected asset group.
Note
You must configure at least one asset group if Allow all asset processing is unselected.Prioritize the Acquia DAM Bulk Asset Import feature over the asset_created webhook event when you import multiple assets.
Select one of the following registration buttons:
Register essential webhooks: Registers asset_deleted, asset_metadata_value_updated, and asset_version_added.
Register selected webhooks: Registers only the event types selected in the Webhook events list.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Acquia DAM (Widen)
If you selected Asset created, configure automatic media creation. To create a Drupal media entity for every new DAM upload, select Allow all asset processing. This setting applies to every new upload in your Acquia DAM account. Use this setting with caution. For more controlled processing, leave Allow all asset processing unselected and configure specific DAM asset groups:
Select Add asset group.
Select a DAM asset group from the list.
To restrict automatic media creation to specific media bundle types, select Filter assets by media type and select one or more media types.
Add additional asset group rows as needed.
If you do not select any media types, Drupal allows all Acquia DAM (Widen) media types for the selected asset group.
Note
You must configure at least one asset group if Allow all asset processing is unselected.Prioritize the Acquia DAM Bulk Asset Import feature over the asset_created webhook event when you import multiple assets.
Select one of the following registration buttons:
Register essential webhooks: Registers asset_deleted, asset_metadata_value_updated, and asset_version_added.
Register selected webhooks: Registers only the event types selected in the Webhook events list.
Did not find what you were looking for?
If this content did not answer your questions, try searching or contacting our support team for further assistance.
Acquia DAM (Widen)