> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Send real-time event data from the HoopAI Platform to external applications using outbound webhooks and the Private Integrations API.

Webhooks let you push data out of the HoopAI Platform to external applications in real time. When a specified event occurs — such as a new contact being created, an opportunity stage changing, or a form being submitted — the platform sends an HTTP POST request containing event data to a URL you control.

This is the foundation for building custom integrations, syncing data to external systems, and triggering automations in third-party tools.

## Types of webhook integrations

| Type                                     | Where to configure              | Use case                                                        |
| ---------------------------------------- | ------------------------------- | --------------------------------------------------------------- |
| **Outbound webhooks (Workflow actions)** | Automation > Workflow actions   | Trigger an HTTP call when a specific workflow step runs         |
| **Inbound webhooks (Premium triggers)**  | Automation > Premium triggers   | Receive data from external systems to trigger a workflow        |
| **API-based webhooks**                   | Settings > Private integrations | Subscribe to account events via the API v2 webhook subscription |

***

## Outbound webhooks via automation

The most common way to send data from the platform to an external system is through the **Webhook** action in a workflow.

<Steps>
  <Step title="Create or open a workflow">
    Go to **Automation > Workflows** and open an existing workflow or create a new one.
  </Step>

  <Step title="Add a Webhook action">
    Click **+** to add an action, then search for and select **Webhook**.
  </Step>

  <Step title="Configure the endpoint">
    * **Method** — select `POST` (recommended), `GET`, `PUT`, or `DELETE`
    * **URL** — enter the destination webhook URL from your external system (e.g., Zapier Webhook URL, Make.com URL, or your own server)
    * **Headers** — add authentication headers if required (e.g., `Authorization: Bearer your-token`)
    * **Body** — choose JSON or Form format and map the fields you want to send
  </Step>

  <Step title="Use custom values and merge fields">
    Use merge tags (e.g., `{{contact.email}}`, `{{contact.full_name}}`, `{{opportunity.name}}`) to dynamically populate the webhook body with contact or opportunity data.
  </Step>

  <Step title="Test the webhook">
    Use a tool like [Webhook.site](https://webhook.site) or [RequestBin](https://requestbin.com) to capture and inspect test payloads before sending to your production endpoint.
  </Step>
</Steps>

<Note>
  Webhook actions require a published workflow. Test mode workflows do not send real webhook requests to external servers.
</Note>

***

## Inbound webhooks (premium trigger)

Use the **Inbound Webhook** premium trigger to receive data from an external system and use it to trigger a workflow inside the platform.

**Steps:**

1. In a workflow, set the trigger to **Inbound Webhook**.
2. The platform generates a unique webhook URL for this workflow.
3. Configure your external system to POST data to this URL.
4. Map the incoming JSON fields to contact or custom fields in the workflow.

This is useful for receiving data from external forms, Zapier, Make.com, or any system that can make HTTP POST requests.

***

## API v2 webhook subscriptions

Using the platform API v2, you can programmatically subscribe to account-level events and receive webhook notifications for any supported event type.

**Supported event categories include:**

* Contact created / updated / deleted
* Opportunity stage changed
* Form submitted
* Appointment booked / cancelled
* Payment received
* Conversation message received

**To set up API webhook subscriptions:**

1. Create a Private Integration with the appropriate scopes (see [Private integrations](/settings/private-integrations)).
2. Use the API v2 `/webhooks` endpoint to create a webhook subscription.
3. Provide your endpoint URL and select the event types to subscribe to.
4. Verify the subscription using the confirmation token sent to your endpoint.

<Tip>
  Use the [API Reference](/api-reference/introduction) and your Private Integration access token to manage webhook subscriptions programmatically.
</Tip>

***

## Webhook payload structure

Webhook payloads are sent as JSON. A typical event payload includes:

```json theme={null}
{
  "type": "ContactCreated",
  "locationId": "your-location-id",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "contact-id",
    "email": "contact@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+15551234567",
    "tags": ["lead", "website-form"]
  }
}
```

***

## Security and authentication

To verify that webhook requests originate from the platform:

* **Shared secret / HMAC signature** — configure a secret key and validate the `X-Hmac-Signature` header on incoming requests
* **Authorization headers** — use static bearer tokens in outbound webhook headers
* **IP allowlisting** — restrict your endpoint to accept requests only from known platform IP ranges

<Warning>
  Never expose webhook endpoints without authentication. Always validate the source of incoming webhook requests before processing them.
</Warning>

***

## Troubleshooting webhooks

<AccordionGroup>
  <Accordion title="Webhook not firing">
    * Verify the workflow is published and the webhook action is active
    * Check that the trigger conditions are met for the contact or record
    * Review the workflow execution history for error messages
  </Accordion>

  <Accordion title="Endpoint returns error responses">
    * Ensure your server returns a 2xx response within 30 seconds
    * Check server logs for authentication failures or payload parsing errors
    * Test the endpoint manually using curl or Postman with a sample payload
  </Accordion>

  <Accordion title="Payload fields are missing or empty">
    * Confirm the contact record has the fields you are trying to send
    * Check merge tag syntax — use `{{contact.email}}` not `{{email}}`
    * Enable test mode and inspect the payload before going live
  </Accordion>

  <Accordion title="Duplicate webhook deliveries">
    * The platform may retry failed webhook deliveries. Implement idempotency on your endpoint using a unique event ID to avoid processing duplicates.
  </Accordion>
</AccordionGroup>

***

## Related articles

* [Private integrations](/settings/private-integrations)
* [Automation overview](/automation/overview)
* [API reference](/api-reference/introduction)
* [Integrations](/settings/integrations)