# Webhooks

> Send new leads, conversations, tickets, and other agent events to your CRM or automation tools the moment they happen.

A webhook is a message Hourzero sends to another app the moment something happens, like a new lead, a teammate taking over a chat, or a ticket being closed. Use webhooks to add leads to your CRM, alert your team, sync tickets to another helpdesk, or start your own automations, without copying anything by hand.

**Where to find it:** open your agent, go to **Settings**, and select the **Webhooks** tab.

## How it works

You give Hourzero a web address, called an **endpoint**, and choose which events it should hear about. Each time one of those events happens, Hourzero sends the details to that address.

1. **Something happens**: A customer leaves their email, or a ticket is closed.
2. **Hourzero sends it**: A signed message goes to your endpoint.
3. **Your tool reacts**: It adds the lead to your CRM or alerts your team.
4. **You check it**: Event history shows what was sent and whether it arrived.

Webhooks belong to one agent. If you have several agents, set them up on each agent that should send events.

## What you can do with webhooks

- Add every new lead from Acme Support to your CRM, with the name and email the customer typed.
- Add WhatsApp and Messenger customers to your CRM as soon as they write, using the name or phone number their app shares.
- Post to your team channel when a conversation is escalated to a person, and again when the ticket is resolved.
- Copy every message into your own reporting tool, or send each conversation's sentiment and topics to your analytics.
- Send the knowledge gaps your agent spots to your team's task tracker.
- Hear about a data source that couldn't be processed, or a channel that went offline, before customers notice.

## Before you start

- **Who can set it up:** workspace owners and admins. Other members can see endpoints and event history, but can't change them.
- **Your plan** must include webhooks. If it doesn't, the **Webhooks** tab shows which plans do.
- **An endpoint URL:** the web address that should receive the events. It usually comes from an automation tool, such as Zapier, Make, or n8n, or from your developer if the events go to your own system. Share the [For your developer](#for-your-developer) section with them.

The address must start with `https://`.

## Add an endpoint

1. Open your agent, go to **Settings**, and select the **Webhooks** tab.
2. Under **Webhook endpoints**, select **Add endpoint**.
3. Paste the address into **Endpoint URL**.
4. Optionally, add a **Description**, such as "Production CRM". Your list shows it instead of the address.
5. Under **Events to send**, choose:
   - **All events** to receive everything, including new events Hourzero adds later, or
   - **Selected events** to pick only the ones you need. Use **Search events…** to find one by name.
6. Leave **Include playground events** off, unless test chats from the Playground should be sent too.
7. Select **Create endpoint**.
8. The **Save your signing secret** dialog opens. Copy the secret, give it to whoever set up the receiving side, and select **I saved it**.

The endpoint appears in your list with an **Active** badge, how many events it receives, and the last four characters of its secret.

> [!TIP]
> Send only the events you need. A CRM usually needs **Lead created**, **Contact identified**, and **Contact updated**. Fewer events means less noise on the other side.

Next, [send a test event](#send-a-test-event) to check that everything works.

## Choose your events

The name in `code` is what your developer or automation tool sees. Events marked **Customer data** in the dialog include what customers wrote or typed into forms.

**Conversations**

| Event | Name | Sent when |
| --- | --- | --- |
| **Conversation created** | `conversation.created` | A customer starts a conversation on any channel. |
| **AI paused** | `conversation.ai_paused` | A teammate takes a conversation over from the agent, or an escalation hands it to your team. |
| **AI resumed** | `conversation.ai_resumed` | A conversation is handed back to the agent. |
| **Conversation deleted** | `conversation.deleted` | Someone permanently deletes a conversation. |
| **Message created** | `message.created` | A customer, the agent, or a teammate sends a message. |

**Insights**

| Event | Name | Sent when |
| --- | --- | --- |
| **Conversation analyzed** | `conversation.analyzed` | Insights scores a finished conversation's sentiment and tags its topics. |
| **Suggestion created** | `suggestion.created` | The agent spots a knowledge gap or improvement in a conversation. See [Suggestions](https://hourzero.dev/docs/ai-agent-management/suggestions). |

**Contacts**

| Event | Name | Sent when |
| --- | --- | --- |
| **Contact identified** | `contact.identified` | A customer's name, email, or phone number becomes known for the first time. This happens when they fill in a **Collect leads** form, when a messaging app such as WhatsApp shares it, or when your website signs them in with [identity verification](https://hourzero.dev/docs/integrations/identity-verification). The contact's `external_id` is then your website's user ID. |
| **Contact updated** | `contact.updated` | A known contact's name, email, phone number, or details change. |

**Submissions**

| Event | Name | Sent when |
| --- | --- | --- |
| **Lead created** | `lead.created` | A customer submits a **Collect leads** form. |
| **Submission created** | `submission.created` | A customer submits a **Collect data**, **Custom form**, or escalation form. |

**Helpdesk tickets**

| Event | Name | Sent when |
| --- | --- | --- |
| **Ticket created** | `ticket.created` | A teammate opens a ticket, or the agent escalates a conversation. See [Helpdesk](https://hourzero.dev/docs/ai-agent-management/helpdesk). |
| **Ticket updated** | `ticket.updated` | A ticket's status, priority, assignee, team, tags, subject, or requester changes, including when a customer reply moves it along. |
| **Ticket resolved** | `ticket.resolved` | A ticket moves to a closed or cancelled status. |
| **Ticket reopened** | `ticket.reopened` | A closed or cancelled ticket moves back to an open status. |
| **Ticket deleted** | `ticket.deleted` | Someone permanently deletes a ticket. |

**Ticket resolved** and **Ticket reopened** arrive together with **Ticket updated**, so pick whichever fits your tool.

**Agents, knowledge, and channels**

| Event | Name | Sent when |
| --- | --- | --- |
| **Agent published** | `agent.published` | A new version of the agent goes live on a channel. |
| **Agent rolled back** | `agent.rolled_back` | Someone restores an earlier deployment from history. |
| **Agent archived** | `agent.archived` | Someone archives the agent, which takes it off every channel. |
| **Training succeeded** | `training_run.succeeded` | The agent finishes training on its data sources. |
| **Training failed** | `training_run.failed` | A training run stops with an error, including when it is interrupted. |
| **Data source ready** | `data_source.ready` | A data source finishes processing and is ready for training. |
| **Data source failed** | `data_source.failed` | Hourzero can't process a data source. |
| **Deployment activated** | `deployment.activated` | A channel goes live, or its live version or settings change. |
| **Deployment disabled** | `deployment.disabled` | A channel stops being live, for example when it's unpublished or the agent is archived. |

The deployment events arrive together with **Agent published**, **Agent rolled back**, or **Agent archived**, one for each channel whose live setup changed. See [Publishing and version history](https://hourzero.dev/docs/ai-agent-management/deployments).

> [!WARNING] Some events contain personal details
> Events marked **Customer data** include what customers wrote, typed into forms, or shared through a messaging app. Only send them to tools you're allowed to store customer data in.

## Send a test event

1. On the endpoint, select **Send test**.
2. Choose an event, such as **Lead created**.
3. Select **Send test event**.

Hourzero sends a sample of that event to this endpoint only, with realistic made-up data and a real signature. **Event history** switches to this endpoint so you can watch the result. Test events have the environment **Test** and aren't retried, and they never count toward an endpoint [failing](#when-an-endpoint-keeps-failing).

## Check that events arrive

**Event history**, below your endpoints, lists this agent's events from the last 7 days, newest first. Each row shows the event, its **Status**, whether it came from **Production** (real customers), the **Playground**, or a **Test**, how many endpoints it went to, and when it happened. Statuses update by themselves while deliveries are in progress.

- **Delivered**: every endpoint accepted it.
- **Processing**: Hourzero is still sending it, or waiting to try again.
- **Failed**: at least one endpoint didn't accept it, and Hourzero stopped trying.
- **Cancelled**: the endpoint was turned off or deleted before delivery.
- **No endpoints**: no active endpoint was listening for this event when it happened.

Use the filters to show one event type, status, environment, or endpoint. To jump to one endpoint's events, open the **⋯** menu on it and select **View deliveries**. Select **Clear** to see everything again.

To look closer, select the eye icon on a row. You see the exact message that was sent under **Event payload**, each endpoint under **Deliveries**, and every try under **Attempts**. Select an attempt to see the error and the reply the other side sent back.

## Resend an event

If an event failed because the other tool was down or set up wrong, fix the problem first. You don't need to wait for the next automatic retry. Then:

1. In **Event history**, select the eye icon on the event.
2. Under **Deliveries**, select the endpoint you want to send it to again.
3. Select **Resend**.

To send an event to an endpoint that never got it, for example one that was turned off or added later, choose the endpoint next to **Deliveries** and select **Send**.

## When an endpoint keeps failing

If every delivery to an endpoint fails, Hourzero lets you know:

1. After a day, the endpoint shows a **Failing** badge, and workspace owners and admins get a notification and an email.
2. After three days, Hourzero disables the endpoint so it stops receiving events, and lets owners and admins know again. Its badge changes to **Disabled automatically**.

A single successful delivery clears the failing state, and so does changing the endpoint's address. To turn a disabled endpoint back on, fix the receiving side, select **Edit**, turn on **Endpoint active**, and save. Then [send the events you missed](#resend-an-event).

## Edit, pause, or delete an endpoint

- **Change events or the address:** select **Edit**, make your changes, and select **Save endpoint**.
- **Pause deliveries:** select **Edit**, turn off **Endpoint active**, and save. A paused endpoint doesn't receive new events, and events waiting to be sent are cancelled.
- **Delete an endpoint:** open the **⋯** menu and select **Delete endpoint**. Events waiting to be sent are cancelled. Past events and their delivery details stay in Event history.

## Manage the signing secret

The signing secret lets the receiving side check that a message really came from Hourzero.

- **See it again:** open the **⋯** menu on the endpoint and select **Reveal secret**.
- **Replace it:** open the **⋯** menu and select **Roll secret**. Choose when the current secret expires: **Immediately**, or in 1, 12, or 24 hours. Until then, every message is signed with both secrets, so you can update the receiving side without it rejecting any events. Copy the new secret from the dialog that opens.

The endpoint shows when the previous secret stops working.

> [!WARNING] Choose "Immediately" only if the secret leaked
> With **Immediately**, the old secret stops working from the next event. The receiving side rejects events until it has the new secret.

## For your developer

This section has the technical details for whoever builds or maintains the receiving side.

### Requests

Each event is an HTTP `POST` with a JSON body and these headers:

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json; charset=utf-8` |
| `Hourzero-Signature` | `t=<unix timestamp>,v1=<hex signature>`, with a second `v1` while a rolled secret is still valid |
| `X-Hourzero-Event-Id` | The event `id` |
| `X-Hourzero-Event-Type` | The event `type` |
| `X-Hourzero-Delivery-Attempt` | `1` for the first try, counting up on each retry |
| `User-Agent` | `Hourzero-Webhooks/1.0` |

The endpoint URL must use `https://`, be at most 2,048 characters, and resolve to a public address. URLs with a username, password, or `#fragment` are rejected, and so are private, local, and reserved network addresses, both when you save the endpoint and on every delivery. Redirects are not followed.

### Event envelope

Every event uses the same envelope. `data.object` holds the record the event is about, and its shape depends on `type`.

| Field | Meaning |
| --- | --- |
| `id` | Unique event id, starting with `evt_`. Use it to skip duplicates. |
| `object` | Always `event`. |
| `api_version` | The payload version, currently `2026-09-10`. New events and fields are added without changing it. |
| `type` | The event name, such as `lead.created`. |
| `created_at` | When the event happened, in ISO 8601 UTC. Use it to order events. |
| `organization_id` | The workspace. |
| `agent_id` | The agent. |
| `environment` | `production` for real customers, `playground` for test chats, `test` for samples sent with **Send test**. |
| `data.object` | The record, described below. |
| `data.previous_attributes` | On update events, the previous values of only the fields that changed. |

Here is a `ticket.updated` example where a teammate raised the priority and took the ticket:

```json
{
  "id": "evt_Qm3c8VfR2kXn7pLs0aTyB1wZ",
  "object": "event",
  "api_version": "2026-09-10",
  "type": "ticket.updated",
  "created_at": "2026-10-11T09:41:12.000Z",
  "organization_id": "Xr7Kq2mVt9LpA4sD",
  "agent_id": "6f1c2b9e-4d3a-4e8f-9b2a-7c5d1e0f3a21",
  "environment": "production",
  "data": {
    "object": {
      "id": "1042",
      "object": "ticket",
      "number": 1042,
      "external_id": null,
      "conversation_id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c65",
      "contact_id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
      "requester": { "name": "Jordan Lee", "email": "jordan@example.com", "phone": null },
      "subject": "Damaged parcel, wants a replacement",
      "description": "The customer received order A-10482 damaged.",
      "status": { "id": "2d4f…", "category": "on_you", "label": "Waiting on you", "external_label": "In progress" },
      "priority": "high",
      "type": "ticket",
      "origin": "conversation",
      "channel": "whatsapp",
      "assignee": { "id": "user_8sK2", "name": "Maya Chen", "email": "maya@example.com" },
      "team": { "id": "7a1c…", "name": "Support" },
      "tags": [{ "id": "c3e9…", "name": "Shipping" }],
      "last_message_by": "customer",
      "rating": null,
      "resolved_at": null,
      "created_at": "2026-10-11T09:12:40.000Z",
      "updated_at": "2026-10-11T09:41:12.000Z"
    },
    "previous_attributes": {
      "priority": "normal",
      "assignee": null
    }
  }
}
```

### Objects

| `data.object.object` | Events | Main fields |
| --- | --- | --- |
| `conversation` | `conversation.*` | `id`, `agent_id`, `agent_version_id`, `environment`, `channel`, `external_thread_id`, `title`, `ai_paused`, `participants`, `created_at`. A deleted conversation has only `id`, `deleted: true`, and `deleted_at`. |
| `message` | `message.created` | `id`, `conversation_id`, `actor_type` (`end_user`, `agent`, `workspace_member`, or `system`), `participant_id`, `contact_id`, `workspace_user_id`, `role`, `parts`, `attachments`, `created_at`. |
| `conversation_analysis` | `conversation.analyzed` | `id` and `conversation_id` (both the conversation), `sentiment` (`positive`, `neutral`, `negative`, `mixed`, or `unknown`), `confidence` from 0 to 1, `rationale`, `concepts` (each with `id`, `kind`, and `label`), `message_count`, `last_message_at`, `analyzed_at`. |
| `suggestion` | `suggestion.created` | `id`, `conversation_id`, `kind`, `title`, `observation`, `proposed_improvement`, `labels`, `created_at`. |
| `contact` | `contact.*` | `id`, `name`, `email`, `phone`, `metadata`, `created_at`, `updated_at`. |
| `submission` | `lead.created`, `submission.created` | `id`, `action_id`, `action_key`, `action_kind`, `conversation_id`, `contact_id`, `data` (keyed by your form's field keys), `created_at`. |
| `ticket` | `ticket.*` | As in the example above. `status.category` is `new`, `on_you`, `on_customer`, `on_hold`, `closed`, or `cancelled`. `rating` is null until the customer rates the resolved conversation, then `{ "score": 1–5, "comment": "…" or null, "rated_at": "…" }`; a new or changed rating sends `ticket.updated`. A deleted ticket has only `id`, `number`, `deleted: true`, and `deleted_at`. |
| `agent` | `agent.*` | `id`, `public_id`, `name`, `status`. Published and rolled back events add `published_version_id`, `published_version`, `previous_published_version_id`, `published_at`; archived events add `archived_at`. |
| `training_run` | `training_run.*` | `id`, `agent_version_id`, `trigger`, `status`, `requested_at`, `started_at`, `completed_at`, `error_code`, `error_message`, `usage`. |
| `data_source` | `data_source.*` | `id`, `source_type`, `name`, `status`, `error`, `updated_at`. |
| `deployment` | `deployment.*` | `id`, `channel`, `status`, `agent_version_id`, `agent_version`, `deployment_record_id` (all three `null` once disabled), `config`, `updated_at`. |

`message.created` describes the message as it was first saved. Fields can be added to any object over time, so ignore fields you don't recognize.

### Verify the signature

The `v1` value is an HMAC-SHA256, in hex, of the timestamp `t`, a period, and the raw request body. The key is the full signing secret, including its `whsec_` prefix. Accept the request if any `v1` value matches, and reject it if none does or if the timestamp is more than five minutes from your server's clock.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyHourzeroSignature(
  rawBody: string,
  header: string,
  secret: string,
) {
  const values = new Map<string, string[]>();
  for (const part of header.split(",")) {
    const separator = part.indexOf("=");
    if (separator === -1) continue;
    const key = part.slice(0, separator).trim();
    const value = part.slice(separator + 1).trim();
    values.set(key, [...(values.get(key) ?? []), value]);
  }

  const timestamp = Number(values.get("t")?.[0]);
  if (!Number.isSafeInteger(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest();
  return (values.get("v1") ?? []).some((signature) => {
    const received = Buffer.from(signature, "hex");
    return (
      received.length === expected.length &&
      timingSafeEqual(received, expected)
    );
  });
}
```

Compute the signature over the body exactly as received. If you parse the JSON and turn it back into text first, the bytes change and the signature won't match. When a secret is rolled, both the old and new secret produce a matching `v1` until the old one expires, so you can switch your receiver to the new secret at any point in that window.

### Responses and retries

- Reply with any `2xx` status within 15 seconds to confirm you received the event. Do slow work afterwards, for example in a background job.
- Network errors, timeouts, and `408`, `409`, `425`, `429`, and `5xx` replies are retried. Any other reply, including redirects and other `4xx` codes, fails the delivery right away.
- Hourzero makes up to 10 attempts, waiting about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, and then a day between tries. It stops retrying three days after the event.
- The same event can arrive more than once, and events can arrive out of order. Use the event `id` to skip duplicates, and `created_at` to order events.
- Events, deliveries, and attempts are kept for 7 days, so they can be inspected and resent until then. To keep events longer, store them on your side as they arrive.

## Troubleshooting

### "Webhook endpoint URL is not allowed"

The address must start with `https://` and point to a public website. Addresses with a username or password, a `#` part, or a private or local network address are refused.

### "Only workspace owners and admins can manage webhooks"

Ask a workspace owner or admin to add or change the endpoint, or to change your role.

### Events show "No endpoints"

No active endpoint was listening for that event when it happened. Check that the event is selected in **Edit**, or choose **All events**. For test chats, also turn on **Include playground events**. You can still [send the event](#resend-an-event) to an endpoint now.

### Events show "Failed"

Select the eye icon on the event and open its attempts. The reply code and response body show how the other side answered, for example `404` if the address is wrong or `401` if it refused the request. Fix the problem on that side, then select **Resend**.

### My endpoint was disabled

Every delivery failed for three days. See [When an endpoint keeps failing](#when-an-endpoint-keeps-failing).

### My developer says the signature doesn't match

Check that they use the current secret, and that they verify the raw body before parsing it. If a secret was rolled with **Immediately**, the old one stopped working right away.

## Next steps

- [Collect leads](https://hourzero.dev/docs/ai-agent-management/actions/collect-leads): Set up the form that sends Lead created events.
- [Helpdesk](https://hourzero.dev/docs/ai-agent-management/helpdesk): Escalate conversations to your team as tickets.
- [Integrations overview](https://hourzero.dev/docs/integrations): Connect your agent to the channels your customers use.
