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.
- 01Something happensA customer leaves their email, or a ticket is closed.
- 02Hourzero sends itA signed message goes to your endpoint.
- 03Your tool reactsIt adds the lead to your CRM or alerts your team.
- 04You check itEvent 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 section with them.
The address must start with https://.
Add an endpoint
- Open your agent, go to Settings, and select the Webhooks tab.
- Under Webhook endpoints, select Add endpoint.
- Paste the address into Endpoint URL.
- Optionally, add a Description, such as "Production CRM". Your list shows it instead of the address.
- 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.
- Leave Include playground events off, unless test chats from the Playground should be sent too.
- Select Create endpoint.
- 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 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. |
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. 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. |
| 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.
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
- On the endpoint, select Send test.
- Choose an event, such as Lead created.
- 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.
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:
- In Event history, select the eye icon on the event.
- Under Deliveries, select the endpoint you want to send it to again.
- 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:
- After a day, the endpoint shows a Failing badge, and workspace owners and admins get a notification and an email.
- 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.
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.
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:
{
"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.
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
2xxstatus 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, and5xxreplies are retried. Any other reply, including redirects and other4xxcodes, 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
idto skip duplicates, andcreated_atto 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 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.
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.