Webhook Connection

Overview

Webhooks are user-defined HTTP callbacks—automated messages sent from one application to another when a specific event occurs. Instead of one system repeatedly asking "Has anything changed?", as with traditional API polling, a webhook automatically pushes the relevant data to a designated URL the moment the event happens.

You can think of webhooks as a smart doorbell for your systems: instead of constantly opening the door to check if something is there, you're instantly notified the moment something actually arrives.

Why This Feature Matters

Without webhooks, keeping downstream systems aligned with Claravine requires manual effort or scheduled API polling—both of which introduce lag, added overhead, and potential for data gaps. The Webhook Connection removes that burden by pushing event data automatically the instant an action occurs.

Common use cases include:

• Triggering downstream workflows automatically when a Submission is completed
• Keeping DAMs, analytics platforms, or databases current with Template changes
• Refreshing or invalidating cached List values the moment a List or Powered List updates in Claravine
• Kicking off data quality validation when a new Submission is created
• Powering asset sync between Claravine and external platforms such as AEM

How It Works

Claravine monitors three object types: Templates, Lists ( Lists and Powered Lists), and Submissions. When any supported event occurs, Claravine sends an HTTP POST to a URL your team configures. That notification includes the event type, a timestamp, the object ID, a direct link to retrieve the full updated object from the Claravine API, the operation performed, and an authentication token.

The process follows four steps:

1. An action occurs in Claravine (for example, a team member creates, updates, or deletes a Template, List, or Submission).
2. Claravine captures the event.
3. The webhook system immediately sends the event details to your configured endpoint as an HTTP POST.
4. Your receiving system takes action—updating records, triggering workflows, or notifying other connected systems.

Delivery is event-driven and immediate. There is no polling interval, sync schedule, or batch window.

What You Need to Know Before Getting Started

• Webhooks are configured on an all-or-nothing basis. Once enabled, Claravine sends notifications for all supported object types—Templates, Lists, and Submissions. It is not currently possible to receive events for only one object type (for example, Submissions only). If your system needs to act selectively, use the event field in each payload to filter on your end.
• There is no self-service setup in the platform UI. Webhook enablement requires backend configuration by the Claravine Engineering team. Your Customer Success Manager will coordinate the setup process.
• Your endpoint must respond within 500 milliseconds. Claravine requires an HTTP 200 OK response within 500ms of delivery. Your endpoint should acknowledge receipt immediately and handle any processing asynchronously. Delivery is marked as failed if the response times out.

How to Enable the Webhook Connection

1. Submit a support ticket requesting webhook enablement for your account.
2. Your Claravine Customer Success Manager coordinates with the Engineering team to configure the connection.
3. Provide two pieces of information:
4. A single HTTPS URL where Claravine will send event notifications
5. A bearer token that Claravine will include in each request header for authentication
6. Claravine Engineering enables the feature and configures your endpoint.
7. Once enabled, Claravine immediately begins delivering event notifications to your configured URL.

Webhook Events by Object Type

Claravine fires webhook notifications for the following events:

Note: Powered List refreshes also trigger List webhook events. Systems sensitive to high List update volume should account for this.

Payload Structure

Every webhook notification is sent as an HTTP POST and uses the same fixed payload structure, regardless of object type:

Field descriptions:

See the Appendix for sample payload outputs by object type (Submissions, Lists, and Templates).

Tips and Best Practices

• Respond immediately, process later. Your endpoint should return HTTP 200 right away and queue the payload for asynchronous processing. Any synchronous work done before responding risks exceeding the 500ms limit and causing delivery failures.
   
• Filter on your end if needed. Because notifications fire for all object types, use the event field in each payload to determine whether your system needs to act on that specific notification.
   
• Validate the bearer token on every request. Claravine sends the token both inside the JSON payload body and in the Authorization request header. Check this token on every inbound request to confirm it originated from Claravine.
   
• Account for Powered List refresh volume. Powered List refreshes trigger List webhook events. If your system is sensitive to high List update volume, implement filtering or rate-limiting logic on your end.
   
• Keep your endpoint available and monitored. Webhook delivery fails if your endpoint is unreachable. Ensure your receiving system has appropriate uptime and alerting in place.

Getting Help

To request webhook enablement or get technical support, submit a ticket through the Claravine support portal. Your Customer Success Manager will guide you through requirements, coordination, and activation to ensure a secure and successful implementation.