Getting started with webhooks

Last published: 2026-06-01

Webhooks at Baack provide a robust, event-driven mechanism to move from a "pull" model to real-time integrations. With over 80% of the API surface covered, webhooks allow your application to receive instant updates whenever data changes on the platform.

API Client Creation

Before setting up webhooks, you must have a valid API Client and a Bearer Token if you intend to use Bearer authentication for your administrative requests to the Baack API.

  • Sign Up/Log In: Access the Baack developer portal.
  • Create a webhook client: Navigate to the "API Clients" section of your dashboard and select "New API client".
  • Scope: Ensure your client is provisioned with the correct scope, typically webhook.baack.co. Only clients scoped to the webhooks sub-domain can subscribe to events. This restriction prevents webhook clients from accessing general api scopes.
  • Authorization: Select "Full Access" for your webhook client, or manually grant fine-grained permissions for specific subjects.
  • Client Identifier: For Basic or Digest authentication, set the client ID to the expected username. For Bearer authentication, the client ID is ignored in favor of the token.

Webhook Subscription Setup

Baack supports fine-grained subscriptions, allowing you to "listen" only to the specific events your product requires.

Subscription Parameters

Subscriptions can be configured for individual subjects (e.g., a specific message thread) with the following event types:

  • Create: Triggered when a new resource is generated.
  • Update: Triggered when an existing resource is modified.
  • Delete: Triggered when a resource is removed.
  • All: A catch-all for all lifecycle events of the subject.

To manage these, use the Webhook Subscription endpoint.

  • Create a subscription: In the "Webhooks" dashboard, select "New Webhook Subscription".
  • Select Client: Choose the appropriate client from your provisioned list.
  • Subject: Select the webhook subject e.g. Entity to receive updates about content entity changes.
  • Event Type: Select the specific event type. Choosing "ALL" captures the full resource lifecycle.
  • Destination URL: Provide the endpoint URL that will receive the JSON webhook events.
  • Subscription end time: All subscriptions are for up to 90 days. They can be renewed via the subscription API.
  • Authentication: Select the authentication method the Baack service should use when calling your endpoint.
  • Webhook Secret: Define a secret token for HMAC-SHA256 signatures and chosen authentication mechanisms.
  • Rate Limiting: Define the maximum delivery attempts per minute to prevent overwhelming your infrastructure.

Webhook Authentication

Baack offers flexible, standards-based authentication mechanisms to ensure that delivery to your integration is secure and compatible with your existing infrastructure.

Authentication Method Description
HTTP BASIC Uses the API Client ID as the username and the Subscription Secret as the password.
DIGEST Standard challenge-response mechanism using the following formulas: HA1 = MD5(username:realm:password) HA2 = MD5(method:digestURI) response = MD5(HA1:nonce:HA2)
BEARER Standard token-based authentication using the Bearer token associated with the API Client.
mTLS Mutual TLS for high-security environments; available upon request.
HMAC-SHA256 Signature-only verification. The signature is calculated as: HMAC-SHA256(payload, secret) payload = body + timestamp + idempotencyKey

Note: the signature is always provided.

Webhook Payload and Delivery

The delivery mechanism prioritizes speed and reliability through a "fast-then-slow" retry strategy. Initial delivery attempts are rate-limited based on your subscription's events-per-minute configuration.

Integrations should use the Idempotency-Key header (the trigger URN) to detect duplicates. For versioned resources, the vectorClock field should be used to ensure updates are processed in the correct order.

Delivery Characteristics

  • Latency: Initial delivery attempts are targeted to start within 100ms of the update being committed to the platform. Subsequent requests are increasingly delayed to allow infrastructure to recover from outages.
  • Retries: If delivery fails in a retryable way, Baack utilizes a "back-off" approach, attempting delivery over a 24-hour period before stopping the subscription.
  • Payload Inspection: Deliveries include the original trigger, allowing you to inspect the exact event that caused the webhook.
  • Rate Limiting: Throttling can be configured at the subscription level. The platform supports up to 6,000 deliveries per minute by default.

The payload is intended to be as simple as possible to allow an integration to determine how to route the update. Webhook event messages do not provide the content of the representation for security reasons.

Failed deliveries due to timeouts (HTTP 408, 418) or server errors (HTTP 429, 503, 504) follow an exponential back-off schedule (approx. 8s, 16s, 60s, 8m, etc.), with the final attempt occurring roughly 16 hours after the initial failure.

If retries all fail or if there are a significant number of delivery failures then the subscription will expire automatically. Please verify that the endpoint is functional before re-enabling the subscription as delivery attempts count against your billable requests.

Webhook Verification

To ensure the integrity and authenticity of the data received, every webhook includes security headers to prevent spoofing and replay attacks.

  • HMAC-SHA256 Signature: A standard signature is included in every delivery, allowing you to verify that the message was sent by Baack and has not been tampered with. See above for details on how to verify the signature and refer to the ‘Signed-Headers’ for the spec on verifying the signature.
  • Timestamps & Nonces: Used to ensure the freshness of the request and protect your endpoint from replay attacks.
  • Idempotency Keys: We recommend building your integration to handle replays based on the provided idempotency keys or representation versions, which facilitates easy debugging and recovery from outages.

For assistance with integration testing or to request mTLS setup, please contact support@.