Skip to main content
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

TypeWhere to configureUse case
Outbound webhooks (Workflow actions)Automation > Workflow actionsTrigger an HTTP call when a specific workflow step runs
Inbound webhooks (Premium triggers)Automation > Premium triggersReceive data from external systems to trigger a workflow
API-based webhooksSettings > Private integrationsSubscribe 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.
1

Create or open a workflow

Go to Automation > Workflows and open an existing workflow or create a new one.
2

Add a Webhook action

Click + to add an action, then search for and select Webhook.
3

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
4

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.
5

Test the webhook

Use a tool like Webhook.site or RequestBin to capture and inspect test payloads before sending to your production endpoint.
Webhook actions require a published workflow. Test mode workflows do not send real webhook requests to external servers.

​
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).
  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.
Use the API Reference and your Private Integration access token to manage webhook subscriptions programmatically.

​
Webhook payload structure

Webhook payloads are sent as JSON. A typical event payload includes: 
{
  "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
Never expose webhook endpoints without authentication. Always validate the source of incoming webhook requests before processing them.

​
Troubleshooting webhooks

  • 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
  • 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
  • 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
  • The platform may retry failed webhook deliveries. Implement idempotency on your endpoint using a unique event ID to avoid processing duplicates.
Last modified on March 4, 2026