CloudAMQP Console Webhooks

Sometimes applications need to be able to act and react to real-time data from other applications, and to do so, they need to communicate. Webhooks (or web callback, HTTP push API) are used to push data as soon as it’s received to its recipients, meaning that applications are notified directly with the trigger of an alarm or a specific action on a website.

Using webhooks allows for data to be pushed directly instead of periodically polling for new data (as for APIs), making application interaction instant. Use webhooks if you need a real-time notification of events, e.g., alarm notifications can be received via webhooks (link to monitoring alarms.)

Webhooks will do a POST request for any messages placed in a specified queue to a specified URL. A POST request will be made for each message in the queue with the AMQP message body as the HTTP-request body. If the endpoint returns a HTTP status code in the 200 range, the message will be acknowledged and removed from the queue, otherwise it will retry to POST it again.

Any headers included with the AMQP message will be inserted to the HTTP request headers. Be aware that this can lead to some issues with some HTTP endpoints. For example, the content-type for an AMQP message may not align with accepted content-type for the HTTP endpoint.

A webhook can be configured from the Webhook view in the CloudAMQP console or through the API.

Add webhook/push-queue

vhost [vhost] The vhost the queue resides in.
Queue [queue name] *A (durable) queue on your RabbitMQ instance (in your default vhost).*
Endpoint [host endpoint] *A POST request will be made for each message in the queue to this endpoint. If the endpoint returns a HTTP status code in the 200 range the message will be acknowledged and removed from the queue, otherwise retried.*
Concurrency [number] Max simultaneous outstanding requests to the endpoint.
Timeout [timeout] Maximum HTTP request processing timeout. Max 90s. Default 30s.
Signing Secret [secret key] *Optional secret key for HMAC-SHA256 signature verification. When configured, webhook requests will include webhook-id, webhook-timestamp, and webhook-signature headers. Multiple secrets can be provided (space-separated) to enable zero-downtime key rotation.*

Webhook Signature Verification

For enhanced security, webhooks support signature verification using HMAC-SHA256. When you configure a signing secret for your webhook, CloudAMQP will include the following headers in each webhook request:

webhook-id Unique message identifier (e.g., msg_2a3b4c5d...)
webhook-timestamp Unix timestamp in seconds (e.g., 1234567890)
webhook-signature HMAC-SHA256 signature (format: v1,<base64>)

The signature is computed over the concatenation of the webhook ID, timestamp, and request body: {webhook-id}.{webhook-timestamp}.{body}

To verify webhook signatures in your application:

  1. Extract the webhook-id, webhook-timestamp, and webhook-signature headers

  2. Verify the timestamp is within acceptable tolerance (e.g., 5 minutes) to prevent replay attacks

  3. Construct the signed content: {webhook-id}.{webhook-timestamp}.{body}

  4. Compute the HMAC-SHA256 signature of the signed content using your signing secret

  5. Compare signatures using a timing-safe comparison

Key Rotation

To rotate signing secrets without downtime, CloudAMQP supports multiple space-separated secrets. When multiple secrets are configured, signatures are generated for all of them, allowing your webhook consumers to verify with any key during the transition period.

To rotate keys:

  1. Add a new secret by appending it (space-separated) to the existing one: new-secret old-secret

  2. Update your webhook consumers to use the new secret for verification

  3. Remove the old secret, keeping only the new one

Handling webhook message failure

When a message fails on delivery for 7 consecutive days it will be rejected, these messages can be recovered by setting up a DLX: When and how to use dead letter exchange

RabbitMQ variable shovel plugin, which allows RabbitMQ to call a webhook for each message in a queue: RabbitMQ vshovel plugin.