Skip to main content
Webhooks let your application receive real-time HTTP notifications whenever an event occurs in the HoopAI Platform. Instead of polling the API for changes, you register an endpoint and the platform pushes a POST request to your URL the moment an event fires. The HoopAI Platform supports 50+ webhook events spanning contacts, conversations, appointments, opportunities, payments, tasks, objects, and more — giving you the building blocks to create deeply integrated, event-driven workflows.

​
Setting up a webhook endpoint

Configure webhook endpoints in one of two ways:
  1. Platform UI — navigate to Settings → Integrations → Webhooks and add your endpoint URL.
  2. Programmatically — use the API to register and manage webhook subscriptions.
Your endpoint must:
  • Be publicly reachable over HTTPS
  • Respond with an HTTP 200 status within 10 seconds
  • Accept POST requests with a Content-Type: application/json body
If your endpoint fails to respond or returns a non-2xx status, the platform will retry the delivery with exponential backoff.

​
Webhook payload structure

Every webhook delivery shares the same top-level envelope. The type field identifies the event, and the remaining fields carry the event-specific data. 
{
  "type": "ContactCreate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "nmFmQEsNgz6AVpgLVUJ0",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "dateAdded": "2024-06-01T09:30:00.000Z"
}
The fields present alongside type and locationId vary by event. See each individual event page for its full schema and an example payload.

​
Sample payload — contact created

{
  "type": "ContactCreate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "nmFmQEsNgz6AVpgLVUJ0",
  "firstName": "Jane",
  "lastName": "Smith",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "address1": "123 Main St",
  "city": "Austin",
  "state": "TX",
  "postalCode": "78701",
  "country": "US",
  "source": "landing-page-form",
  "dateAdded": "2024-06-01T09:30:00.000Z",
  "dnd": false,
  "tags": ["prospect", "webinar-2024"],
  "customFields": [
    {
      "id": "BcdmQEsNgz6AVpgLVUJ0",
      "value": "Acme Corp"
    }
  ],
  "assignedTo": "userId123"
}

​
Signature verification

Every webhook request includes an x-wl-signature header containing an HMAC-SHA256 signature. Always verify this signature before processing a payload to confirm the request originated from the HoopAI Platform and was not tampered with in transit. Verification steps:
  1. Retrieve the raw request body as a string (do not parse it first).
  2. Compute HMAC-SHA256(rawBody, yourWebhookSecret).
  3. Compare your computed digest to the value in the x-wl-signature header using a constant-time comparison.
  4. Reject the request if the signatures do not match.
const crypto = require('crypto');

function verifyWebhookSignature(rawBody, secret, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signatureHeader, 'hex')
  );
}
See Webhook authentication for the full reference.

​
Event categories

​
Contacts

EventDescription
Contact createdA new contact was added to the platform
Contact updatedA contact’s fields were modified
Contact deletedA contact was removed
Contact DND updatedA contact’s do-not-disturb status changed
Contact tag updatedTags were added or removed from a contact

​
Conversations

EventDescription
Inbound messageA message was received from a contact
Outbound messageA message was sent to a contact
Conversation unreadA conversation has unread messages
Provider outbound messageA message was sent via an external provider

​
Appointments

EventDescription
Appointment createdA new appointment was booked
Appointment updatedAn appointment was modified
Appointment deletedAn appointment was cancelled or removed

​
Opportunities

EventDescription
Opportunity createdA new opportunity was created
Opportunity updatedAn opportunity was modified
Opportunity deletedAn opportunity was removed
Stage updatedAn opportunity moved to a new pipeline stage
Status updatedAn opportunity’s status changed
Value updatedAn opportunity’s monetary value changed
Assignment updatedAn opportunity was reassigned

​
Payments

EventDescription
Invoice createdA new invoice was generated
Invoice sentAn invoice was sent to a contact
Invoice paidAn invoice was paid in full
Invoice partially paidA partial payment was received
Invoice voidedAn invoice was voided
Invoice updatedAn invoice was modified
Invoice deletedAn invoice was deleted
Order createdA new order was placed
Order status updatedAn order’s fulfilment status changed

​
Products and prices

EventDescription
Product createdA new product was added
Product updatedA product was modified
Product deletedA product was removed
Price createdA new price was added to a product
Price updatedA price was modified
Price deletedA price was removed

​
Tasks

EventDescription
Task createdA new task was created
Task completedA task was marked complete
Task deletedA task was removed

​
Notes

EventDescription
Note createdA note was added to a contact
Note updatedA note was modified
Note deletedA note was removed

​
Sub-accounts and users

EventDescription
User createdA new user was added
Location createdA new sub-account was provisioned
Location updatedA sub-account’s details were modified

​
Objects and associations

EventDescription
Object schema createdA new custom object schema was defined
Object schema updatedA custom object schema was modified
Record createdA new custom object record was created
Record updatedA custom object record was modified
Record deletedA custom object record was removed
Relation createdA relation between records was created
Relation deletedA relation was removed
Association createdAn association was created
Association updatedAn association was modified
Association deletedAn association was removed

​
App lifecycle

EventDescription
App installedYour app was installed in a location
App uninstalledYour app was removed from a location
External auth connectedAn external authentication provider was connected
Plan changedA location’s plan or subscription changed
Campaign status updatedA campaign’s status changed
Last modified on March 4, 2026