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

# Webhook Events Overview

> Receive real-time event notifications from the HoopAI Platform REST API using webhooks. React instantly to contact activity, appointments, payments, opportunities, and 50+ other platform events.

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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```javascript theme={null}
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](/api-reference/oauth/webhook-authentication) for the full reference.

## Event categories

### Contacts

| Event                                                             | Description                               |
| ----------------------------------------------------------------- | ----------------------------------------- |
| [Contact created](/api-reference/webhooks/contact-create)         | A new contact was added to the platform   |
| [Contact updated](/api-reference/webhooks/contact-update)         | A contact's fields were modified          |
| [Contact deleted](/api-reference/webhooks/contact-delete)         | A contact was removed                     |
| [Contact DND updated](/api-reference/webhooks/contact-dnd-update) | A contact's do-not-disturb status changed |
| [Contact tag updated](/api-reference/webhooks/contact-tag-update) | Tags were added or removed from a contact |

### Conversations

| Event                                                                          | Description                                 |
| ------------------------------------------------------------------------------ | ------------------------------------------- |
| [Inbound message](/api-reference/webhooks/inbound-message)                     | A message was received from a contact       |
| [Outbound message](/api-reference/webhooks/outbound-message)                   | A message was sent to a contact             |
| [Conversation unread](/api-reference/webhooks/conversation-unread)             | A conversation has unread messages          |
| [Provider outbound message](/api-reference/webhooks/provider-outbound-message) | A message was sent via an external provider |

### Appointments

| Event                                                             | Description                             |
| ----------------------------------------------------------------- | --------------------------------------- |
| [Appointment created](/api-reference/webhooks/appointment-create) | A new appointment was booked            |
| [Appointment updated](/api-reference/webhooks/appointment-update) | An appointment was modified             |
| [Appointment deleted](/api-reference/webhooks/appointment-delete) | An appointment was cancelled or removed |

### Opportunities

| Event                                                                     | Description                                  |
| ------------------------------------------------------------------------- | -------------------------------------------- |
| [Opportunity created](/api-reference/webhooks/opportunity-create)         | A new opportunity was created                |
| [Opportunity updated](/api-reference/webhooks/opportunity-update)         | An opportunity was modified                  |
| [Opportunity deleted](/api-reference/webhooks/opportunity-delete)         | An opportunity was removed                   |
| [Stage updated](/api-reference/webhooks/opportunity-stage-update)         | An opportunity moved to a new pipeline stage |
| [Status updated](/api-reference/webhooks/opportunity-status-update)       | An opportunity's status changed              |
| [Value updated](/api-reference/webhooks/opportunity-value-update)         | An opportunity's monetary value changed      |
| [Assignment updated](/api-reference/webhooks/opportunity-assigned-update) | An opportunity was reassigned                |

### Payments

| Event                                                                    | Description                          |
| ------------------------------------------------------------------------ | ------------------------------------ |
| [Invoice created](/api-reference/webhooks/invoice-create)                | A new invoice was generated          |
| [Invoice sent](/api-reference/webhooks/invoice-sent)                     | An invoice was sent to a contact     |
| [Invoice paid](/api-reference/webhooks/invoice-paid)                     | An invoice was paid in full          |
| [Invoice partially paid](/api-reference/webhooks/invoice-partially-paid) | A partial payment was received       |
| [Invoice voided](/api-reference/webhooks/invoice-void)                   | An invoice was voided                |
| [Invoice updated](/api-reference/webhooks/invoice-update)                | An invoice was modified              |
| [Invoice deleted](/api-reference/webhooks/invoice-delete)                | An invoice was deleted               |
| [Order created](/api-reference/webhooks/order-create)                    | A new order was placed               |
| [Order status updated](/api-reference/webhooks/order-status-update)      | An order's fulfilment status changed |

### Products and prices

| Event                                                     | Description                        |
| --------------------------------------------------------- | ---------------------------------- |
| [Product created](/api-reference/webhooks/product-create) | A new product was added            |
| [Product updated](/api-reference/webhooks/product-update) | A product was modified             |
| [Product deleted](/api-reference/webhooks/product-delete) | A product was removed              |
| [Price created](/api-reference/webhooks/price-create)     | A new price was added to a product |
| [Price updated](/api-reference/webhooks/price-update)     | A price was modified               |
| [Price deleted](/api-reference/webhooks/price-delete)     | A price was removed                |

### Tasks

| Event                                                   | Description                |
| ------------------------------------------------------- | -------------------------- |
| [Task created](/api-reference/webhooks/task-create)     | A new task was created     |
| [Task completed](/api-reference/webhooks/task-complete) | A task was marked complete |
| [Task deleted](/api-reference/webhooks/task-delete)     | A task was removed         |

### Notes

| Event                                               | Description                   |
| --------------------------------------------------- | ----------------------------- |
| [Note created](/api-reference/webhooks/note-create) | A note was added to a contact |
| [Note updated](/api-reference/webhooks/note-update) | A note was modified           |
| [Note deleted](/api-reference/webhooks/note-delete) | A note was removed            |

### Accounts and users

| Event                                                       | Description                        |
| ----------------------------------------------------------- | ---------------------------------- |
| [User created](/api-reference/webhooks/user-create)         | A new user was added               |
| [Location created](/api-reference/webhooks/location-create) | A new account was provisioned      |
| [Location updated](/api-reference/webhooks/location-update) | An account's details were modified |

### Objects and associations

| Event                                                                 | Description                            |
| --------------------------------------------------------------------- | -------------------------------------- |
| [Object schema created](/api-reference/webhooks/object-schema-create) | A new custom object schema was defined |
| [Object schema updated](/api-reference/webhooks/object-schema-update) | A custom object schema was modified    |
| [Record created](/api-reference/webhooks/record-create)               | A new custom object record was created |
| [Record updated](/api-reference/webhooks/record-update)               | A custom object record was modified    |
| [Record deleted](/api-reference/webhooks/record-delete)               | A custom object record was removed     |
| [Relation created](/api-reference/webhooks/relation-create)           | A relation between records was created |
| [Relation deleted](/api-reference/webhooks/relation-delete)           | A relation was removed                 |
| [Association created](/api-reference/webhooks/association-create)     | An association was created             |
| [Association updated](/api-reference/webhooks/association-update)     | An association was modified            |
| [Association deleted](/api-reference/webhooks/association-delete)     | An association was removed             |

### App lifecycle

| Event                                                                      | Description                                       |
| -------------------------------------------------------------------------- | ------------------------------------------------- |
| [App installed](/api-reference/webhooks/app-install)                       | Your app was installed in a location              |
| [App uninstalled](/api-reference/webhooks/app-uninstall)                   | Your app was removed from a location              |
| [External auth connected](/api-reference/webhooks/external-auth-connected) | An external authentication provider was connected |
| [Plan changed](/api-reference/webhooks/plan-change)                        | A location's plan or subscription changed         |
| [Campaign status updated](/api-reference/webhooks/campaign-status-update)  | A campaign's status changed                       |

## Related

* [Webhook authentication](/api-reference/oauth/webhook-authentication) — HMAC signature verification reference
* [OAuth 2.0 overview](/api-reference/oauth/overview) — authenticate your API requests
* [Contacts API](/api-reference/contacts/overview) — query and update contacts referenced in webhook payloads