Acquia DAM Webhooks

DAM Webhooks
Get hooked by our webhooks!

What's a webhook?
A webhook is a way for the Acquia DAM to notify your integration that changes have occurred and allow action to be taken on the information provided. Webhooks are used by web apps to receive small amounts of data from other apps and can also be used to trigger automation workflows when set up properly.

Webhooks are a powerful new capability for DAM API and provide you with useful information about your DAM assets.

DAM webhooks are now available for the following events:

• Asset creation
• Asset deletion
• Asset updates
  • Asset category change
  • Asset tags change
  • Asset release date change
  • Asset expiration date change
  • Asset group change

Setup:
Have your DAM admin enable the Webhook Feature in the Admin app and enable the permission for certain roles.

From there configure webhooks through our API to enable events based on this documentation.

Best practices:
When using webhooks, it's best to set up a user specifically for the purpose of handling and interacting with the events. That way, it's clear and easy to see when something was triggered from an action due to a webhook rather than another action taken elsewhere in DAM. All events are marked with the user responsible for generating them to help prevent a change event loop.

Sample:
By the end of this, you'll be hooked.

Your DAM admin needs to know when users are creating new assets so they can check the assets metadata, asset groups, and security settings.

You can set up a webhook to notify the admin when an asset is created, so long as there is a receiving solution that can handle the events.

First, send a POST request to the webhook creation endpoint.

https://api.widencollective.com/v2/webhooks/configurations

With a body similar to this:

{
 "event_type": "asset_created",
 "delivery_url": "https://MyReciever.MyAppOrService.fake",
 "secret_key": "ShhIt'sASecretToEveryone"
}

On successful creation of the webhook, you will receive back a webhook_configuration_id to verify the setup with.

{
 "webhook_configuration_id": "976cf9b0-95d0-4dbd-acb0-57fbdaef7b6f"
}

Verify that the receiving solution is getting the data by sending a GET request to the ping endpoint with the webhook_configuration_id we received back from the webhook creation process.

https://api.widencollective.com/v2/webhooks/configurations/976cf9b0-95d0-4dbd-acb0-57fbdaef7b6f/ping

You'll then see an event hitting the receiving solution's delivery_url with the ping event_type and a body similar to the following:

{
 "webhook_configuration_id": "976cf9b0-95d0-4dbd-acb0-57fbdaef7b6f",
 "webhook_delivery_id": "88ee7845-7977-4d49-a699-06f678d05c72",
 "event_context": {
 "user": {
 "id": "5f6f1f60-1b5e-4690-8ba0-a40c09b2cf0c",
 "username": "[email protected]"
 }
 },
 "event_type": "ping",
}

Now that you know the connection between DAM and the receiving solution is working, test it by creating an asset. You should receive an event on the delivery_url with a body similar to the following.

{
 "webhook_configuration_id": "976cf9b0-95d0-4dbd-acb0-57fbdaef7b6f",
 "webhook_delivery_id": "a2b622ea-2780-48a6-b591-8a1cc3a34f4d",
 "event_context": {
 "user": {
 "id": "5f6f1f60-1b5e-4690-8ba0-a40c09b2cf0c",
 "username": "[email protected]"
 }
 },
 "asset_id": "3db58e3c-fe98-4437-9637-df299f9d1b06",
 "event_type": "asset_created",
 "date_created": "2021-02-10T22:18:47Z"
}

Now, the receiving solution can use any of our other asset API endpoints to manipulate or check the asset information via the asset_id.

Testing:
We currently offer a means of testing configuration of the webhook via the ping endpoint. It's recommended to validate that your configuration is correct in order to ensure event delivery.

https://api.widencollective.com/v2/webhooks/configurations/c94d0fc3-64b3-4337-8f37-12c656bd7897/ping

This triggers our services to push out a ping message to your supplied receiving endpoint.

Ping body:

{
 "webhook_configuration_id": "c94d0fc3-64b3-4337-8f37-12c656bd7897",
 "webhook_delivery_id": "88ee7845-7977-4d49-a699-06f678d05c72",
 "event_context": {
 "user": {
 "id": "5f6f1f60-1b5e-4690-8ba0-a40c09b2cf0c",
 "username": "[email protected]"
 }
 },
 "event_type": "ping",
}

There is also useful information available on the GET webhook endpoint.

If you were to retrieve this endpoint as an example:

https://api.widencollective.com/v2/webhooks/configurations/c94d0fc3-64b3-4337-8f37-12c656bd7897

You would then receive a body similar to the following.

{ 
 "webhook_configuration_id": "c94d0fc3-64b3-4337-8f37-12c656bd7897",
 "created_by_user": {
 "uuid": "5f6f1f60-1b5e-4690-8ba0-a40c09b2cf0c",
 },
 "event_type": "asset_asset_groups_updated",
 "created_date": "2021-02-10T22:18:47Z",
 "last_delivered_date": "2021-04-18T07:18:33Z",
 "last_pinged_date": "2021-03-12T11:04:13Z",
 "signing_enabled": "false",
 "delivery_enabled": "true",
}

This allows users to view when the last delivery occurred from the webhook, the last time it had been pinged, as well as basic information about the configuration of the webhook.

Security options:
When creating a webhook, if a signing key is supplied, it will be used to generate a HMAC hex digest signature for all events, allowing users to verify the contents are unchanged and from their DAM environment.