Webhook Events Overview - HoopAI Help Center

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:

Platform UI — navigate to Settings → Integrations → Webhooks and add your endpoint URL.
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:

Retrieve the raw request body as a string (do not parse it first).
Compute HMAC-SHA256(rawBody, yourWebhookSecret).
Compare your computed digest to the value in the x-wl-signature header using a constant-time comparison.
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

Event	Description
Contact created	A new contact was added to the platform
Contact updated	A contact’s fields were modified
Contact deleted	A contact was removed
Contact DND updated	A contact’s do-not-disturb status changed
Contact tag updated	Tags were added or removed from a contact

Conversations

Event	Description
Inbound message	A message was received from a contact
Outbound message	A message was sent to a contact
Conversation unread	A conversation has unread messages
Provider outbound message	A message was sent via an external provider

Appointments

Event	Description
Appointment created	A new appointment was booked
Appointment updated	An appointment was modified
Appointment deleted	An appointment was cancelled or removed

Opportunities

Event	Description
Opportunity created	A new opportunity was created
Opportunity updated	An opportunity was modified
Opportunity deleted	An opportunity was removed
Stage updated	An opportunity moved to a new pipeline stage
Status updated	An opportunity’s status changed
Value updated	An opportunity’s monetary value changed
Assignment updated	An opportunity was reassigned

Payments

Event	Description
Invoice created	A new invoice was generated
Invoice sent	An invoice was sent to a contact
Invoice paid	An invoice was paid in full
Invoice partially paid	A partial payment was received
Invoice voided	An invoice was voided
Invoice updated	An invoice was modified
Invoice deleted	An invoice was deleted
Order created	A new order was placed
Order status updated	An order’s fulfilment status changed

Products and prices

Event	Description
Product created	A new product was added
Product updated	A product was modified
Product deleted	A product was removed
Price created	A new price was added to a product
Price updated	A price was modified
Price deleted	A price was removed

Tasks

Event	Description
Task created	A new task was created
Task completed	A task was marked complete
Task deleted	A task was removed

Notes

Event	Description
Note created	A note was added to a contact
Note updated	A note was modified
Note deleted	A note was removed

Accounts and users

Event	Description
User created	A new user was added
Location created	A new account was provisioned
Location updated	An account’s details were modified

Objects and associations

Event	Description
Object schema created	A new custom object schema was defined
Object schema updated	A custom object schema was modified
Record created	A new custom object record was created
Record updated	A custom object record was modified
Record deleted	A custom object record was removed
Relation created	A relation between records was created
Relation deleted	A relation was removed
Association created	An association was created
Association updated	An association was modified
Association deleted	An association was removed

App lifecycle

Event	Description
App installed	Your app was installed in a location
App uninstalled	Your app was removed from a location
External auth connected	An external authentication provider was connected
Plan changed	A location’s plan or subscription changed
Campaign status updated	A campaign’s status changed

Webhook authentication — HMAC signature verification reference
OAuth 2.0 overview — authenticate your API requests
Contacts API — query and update contacts referenced in webhook payloads

​Setting up a webhook endpoint

​Webhook payload structure

​Sample payload — contact created

​Signature verification

​Event categories

​Contacts

​Conversations

​Appointments

​Opportunities

​Payments

​Products and prices

​Tasks

​Notes

​Accounts and users

​Objects and associations

​App lifecycle

​Related