Skip to main content
Webhooks let your integration react to events in HoopAI in real time — no polling required. When something happens (a contact is created, an appointment is booked, a payment is received), HoopAI sends an HTTP POST request to your endpoint.

​
How webhooks work

  1. An event occurs in HoopAI (e.g., contact created, appointment booked)
  2. HoopAI sends a POST request to your registered webhook URL
  3. Your app processes the event and responds with a 2xx status code
  4. If your endpoint doesn’t respond with 2xx, HoopAI retries the delivery

​
Setting up webhooks

​
For marketplace apps

Register webhook subscriptions when your OAuth app is installed. Use the App Marketplace developer portal to configure which events your app listens to.

​
For private integrations

1

Go to webhook settings

Navigate to Settings > Webhooks in your HoopAI account.
2

Add a webhook URL

Enter your endpoint URL and select the events you want to receive.
3

Test the webhook

Click Send Test to verify your endpoint receives the payload correctly.

​
Available events

EventTrigger
ContactCreateA new contact is created
ContactUpdateA contact is updated
ContactDeleteA contact is deleted
ContactTagUpdateTags are added or removed from a contact
ContactDndUpdateDo-not-disturb settings change
AppointmentCreateAn appointment is booked
AppointmentUpdateAn appointment is modified
AppointmentDeleteAn appointment is cancelled
OpportunityCreateA new opportunity is created
OpportunityUpdateAn opportunity is updated
OpportunityStageUpdateAn opportunity moves to a new pipeline stage
InvoiceCreateAn invoice is created
InvoicePaidAn invoice is fully paid
InboundMessageA message is received from a contact
OutboundMessageA message is sent to a contact
NoteCreateA note is added to a contact
TaskCreateA task is created
See the full webhook events reference for every event type and its payload.

​
Webhook payload structure

Every webhook payload follows this structure: 
{
  "type": "ContactCreate",
  "locationId": "loc_abc123",
  "body": {
    "id": "contact_xyz789",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "tags": ["lead"],
    "dateAdded": "2025-03-01T14:30:00.000Z"
  }
}
FieldDescription
typeThe event name (e.g., ContactCreate)
locationIdThe account where the event occurred
bodyThe event payload with resource data

​
Verifying webhook signatures

Always verify that incoming webhooks are genuinely from HoopAI by checking the signature header. 
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return hash === signature;
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-hook-signature'];
  const isValid = verifyWebhook(JSON.stringify(req.body), signature, YOUR_WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  console.log('Event:', req.body.type);
  res.status(200).send('OK');
});
See the webhook authentication guide for details.

​
Best practices

Return a 2xx status code within 5 seconds. If your processing takes longer, accept the webhook and process it asynchronously (e.g., with a queue).
Webhooks may be delivered more than once. Use the event ID or resource ID to deduplicate in your handler.
Always use HTTPS endpoints for webhook URLs to ensure payloads are encrypted in transit.
Track webhook delivery failures and set up alerts. If your endpoint is down, events will be retried but eventually dropped.

​
Next steps

Webhook events reference

See every event type and its payload

Webhook authentication

Verify webhook signatures
Last modified on March 5, 2026