Webhooks Overview

Webhooks are a powerful tool for creating event-driven integrations with the DealHub platform. Instead of you needing to constantly ask DealHub for updates, Webhooks will automatically send a notification to your system whenever a specific event occurs.

How It Works

Webhooks follow an automatic process that is described by the following steps:

An event happens in DealHub (e.g., a sales rep submits a quote, or an admin activates a new version).
DealHub automatically sends an HTTP POST request with a JSON payload to a secure (HTTPS) endpoint URL that you have configured.
Your application, which is listening at that endpoint, receives the notification and triggers a downstream workflow.

This model is ideal for building integrations that need to react in real-time to actions taken by your sales team.

Webhooks Triggers

Webhooks are published for various activities related to the main business entities in DealHub, such as Quotes, Versions, and Users.

The following sections list every available webhook event and the specific actions or status changes that trigger them.

Quote Entity Events

These events track the lifecycle of a Quote (Proposal).

Event Name	Trigger / Description
`draftQuote`	Published when a user creates a quote and saves it as a draft, or modifies an existing draft.
`primaryQuote`	Published when a user or system marks a specific quote as the "Primary" quote.
`quotePendingApproval`	Published when a user submits a quote that requires approval. It is also published as each approver approves their part of the flow.
`quoteReady`	Published when a quote is ready to be shared with the customer. This occurs when a quote requiring approval is fully approved, or when a quote requiring no approval is submitted.
`quoteRejected`	Published when an approver rejects the quote.
`quoteRecalled`	Published when a user explicitly requests to cancel (recall) the quote.
`quotePublished`	Published when the quote is published to a DealRoom.
`quoteUnpublished`	Published if a user unpublishes the DealRoom.
`quoteWon`	Published when the quote is signed (either via DealRoom or externally).

Version Entity Events

These events track the configuration lifecycle (Version entity). The payload for these events includes a specific action field indicating the type of change.

Event Name	Action (`action` field)	Trigger / Description
`version`	`created`	An administrator created a new version from scratch or duplicated an existing version.
`version`	`activated`	An administrator activated a specific version.
`version`	`reactivated`	An administrator reactivated a version.

User Entity Events

These events track changes to users (Sales reps, Administrators, etc.) within the platform. The payload includes an action field specifying the change.

Event Name	Action (`action` field)	Trigger / Description
`user`	`created`	A user was created (e.g., manually by an admin, via API, or upon first authentication).
`user`	`modified`	A user was modified (fields updated, or active status changed by admin).
`user`	`deleted`	A user was deleted from the system.

System & Async Events

These events relate to bulk data processes or asynchronous API requests.

Event Name	Trigger / Description
`productsUpload`	Published when an SFTP product file upload or Open API upload is completed. The payload indicates if the upload status was `success` or `error`.
`Failure WebHook v1`	Published if the system fails to execute an asynchronous API request (e.g., a request to duplicate or activate a version fails).

📘
Webhooks Use Case: BI Integration

Configure a webhook to listen for the quoteWon event.

When a deal is won, your endpoint receives the webhook notification.

Your application extracts the dealhub_quote_id from the payload.

Your application then calls the Get Quote API using that ID to fetch all the detailed line items and answers from the quote.

This detailed data is then logged in your BI system for analysis and reporting.

This workflow allows you to sync rich data without cluttering your CRM, as all the interaction happens directly between your application and DealHub.

The Webhook Payload

Every webhook is sent with a JSON payload containing details about the event. All payloads include a standard event_info object, which contains:

webhook_id: The unique identifier of the webhook configuration.
event_id: A unique identifier for this specific event notification.
api_version: The version of the API that sent the event (currently 1.0).
request_id: A dedicated identifier included only if the event was triggered by an asynchronous API call (e.g., during a product upload or version activation).

For quote-related events, the payload will also contain essential identifiers like dealhub_quote_id and dealhub_opportunity_id, which you can use to make subsequent API calls. You can also configure DealHub to include answers to specific playbook questions in a field called additional_data.

Common Fields

Most business entity payloads (Quote, Version, User) also include:

execution_date: The GMT date and time the action occurred.
executed_by: The login/email of the user who performed the action (or "SYSTEM" for automated actions).
impersonated_by: The login of the admin if they performed the action on behalf of another user.

For quote-related events, you can also configure DealHub to include answers to specific playbook questions in a field called additional_data.

Next Steps

To learn how to configure the Webhooks to start receiving notifications from Dealhub, access the How to Configure Webhooks page.