Information for: DEVELOPERS   PARTNERS

Understanding webhooks

Acquia Content Hub uses webhooks to communicate with the service, enabling your publisher and subscriber websites to communicate through the service as an intermediary. A webhook is an endpoint that the service knows about.

On a publisher or subscriber website, clicking the Update Public URL button in the interface creates a webhook. That registers your website, using the following format as the endpoint:

yourdomain.com/acquia-contenthub/webhook

A webhook defines the messaging endpoint. When information from the service sends to publishers or subscribers, the data sends as a POST request to the HMAC-authenticated endpoint. The Drupal module listens for those requests and performs actions based on the information in the request. Requests requiring actions may include entity creation (a new entity requires import), entity updates (content changes), or other changes.

Acquia Content Hub 2.x requires registering a valid webhook. If there is no registered webhook, some features won’t work. Users may also see errors. Webhook registration failures often occur when the registering website isn’t publicly accessible, such as local development environments.

Changing webhooks

Users can change the webhook URL using the configuration form in the module. This may be necessary if you are working with Acquia Content Hub locally and need the public-accessible URL to be an ngrok tunnel.

Editing or deleting webhooks requires the Content Hub Publisher module.

  1. Sign in to your Acquia Content Hub publisher website as an administrator.
  2. Navigate to Configuration > Acquia Content Hub > Subscription Manager.
  3. Under Administer webhooks:
    • edit the URL field of an existing webhook
    • use Add a new Webhook to add a new webhook
    • remove the URL to delete a webhook
  4. Click Save configuration.

Note

If your website doesn’t have a valid SSL certificate, you must configure your webhooks using HTTP, not HTTPS.

They can also be updated through the Acquia Content Hub API, using a CRUD (create-read-update-delete) operation.

Updated webhooks register if the URL responds with a valid HMAC-authenticated response. You can’t register unauthenticated URLs such as example.com/acquia-contenthub/webhook.

Troubleshooting webhooks

If Acquia Content Hub can’t send webhooks to a subscribing website, it also can’t notify the subscribing website of a problem with the webhook. If a webhook fails or is unreachable for 72 hours, Acquia Content Hub suppresses the webhook for 12 hours. During the 12-hour window, the webhook won’t receive any updates until it’s either manually enabled within the window, or unsuppressed after 12 hours.

After Acquia Content Hub suppresses a webhook, you can enable it again using one of the following methods:

  • Wait 12 hours for Acquia Content Hub to re-enable the webhook.
  • Use the webhook enable API endpoint to manually enable the webhook within the 12-hour window.
  • (For backwards compatibility only) Send a POST request to the v2/settings/webhooks endpoint.

Note

Acquia Content Hub deletes ngrok.io development webhook endpoints unreachable for more than 72 hours.

To review the history logs for Acquia Content Hub, use the /v2/history endpoint. For more information, see Using the Acquia Content Hub API.