Hourzero

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. 01Something happensA customer leaves their email, or a ticket is closed.
  2. 02Hourzero sends itA signed message goes to your endpoint.
  3. 03Your tool reactsIt adds the lead to your CRM or alerts your team.
  4. 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

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

EventNameSent when
Conversation createdconversation.createdA customer starts a conversation on any channel.
AI pausedconversation.ai_pausedA teammate takes a conversation over from the agent, or an escalation hands it to your team.
AI resumedconversation.ai_resumedA conversation is handed back to the agent.
Conversation deletedconversation.deletedSomeone permanently deletes a conversation.
Message createdmessage.createdA customer, the agent, or a teammate sends a message.

Insights

EventNameSent when
Conversation analyzedconversation.analyzedInsights scores a finished conversation's sentiment and tags its topics.
Suggestion createdsuggestion.createdThe agent spots a knowledge gap or improvement in a conversation. See Suggestions.

Contacts

EventNameSent when
Contact identifiedcontact.identifiedA 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 updatedcontact.updatedA known contact's name, email, phone number, or details change.

Submissions

EventNameSent when
Lead createdlead.createdA customer submits a Collect leads form.
Submission createdsubmission.createdA customer submits a Collect data, Custom form, or escalation form.

Helpdesk tickets

EventNameSent when
Ticket createdticket.createdA teammate opens a ticket, or the agent escalates a conversation. See Helpdesk.
Ticket updatedticket.updatedA ticket's status, priority, assignee, team, tags, subject, or requester changes, including when a customer reply moves it along.
Ticket resolvedticket.resolvedA ticket moves to a closed or cancelled status.
Ticket reopenedticket.reopenedA closed or cancelled ticket moves back to an open status.
Ticket deletedticket.deletedSomeone permanently deletes a ticket.

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

Agents, knowledge, and channels

EventNameSent when
Agent publishedagent.publishedA new version of the agent goes live on a channel.
Agent rolled backagent.rolled_backSomeone restores an earlier deployment from history.
Agent archivedagent.archivedSomeone archives the agent, which takes it off every channel.
Training succeededtraining_run.succeededThe agent finishes training on its data sources.
Training failedtraining_run.failedA training run stops with an error, including when it is interrupted.
Data source readydata_source.readyA data source finishes processing and is ready for training.
Data source faileddata_source.failedHourzero can't process a data source.
Deployment activateddeployment.activatedA channel goes live, or its live version or settings change.
Deployment disableddeployment.disabledA 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

  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.

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.

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:

HeaderValue
Content-Typeapplication/json; charset=utf-8
Hourzero-Signaturet=<unix timestamp>,v1=<hex signature>, with a second v1 while a rolled secret is still valid
X-Hourzero-Event-IdThe event id
X-Hourzero-Event-TypeThe event type
X-Hourzero-Delivery-Attempt1 for the first try, counting up on each retry
User-AgentHourzero-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.

FieldMeaning
idUnique event id, starting with evt_. Use it to skip duplicates.
objectAlways event.
api_versionThe payload version, currently 2026-09-10. New events and fields are added without changing it.
typeThe event name, such as lead.created.
created_atWhen the event happened, in ISO 8601 UTC. Use it to order events.
organization_idThe workspace.
agent_idThe agent.
environmentproduction for real customers, playground for test chats, test for samples sent with Send test.
data.objectThe record, described below.
data.previous_attributesOn 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.objectEventsMain fields
conversationconversation.*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.
messagemessage.createdid, conversation_id, actor_type (end_user, agent, workspace_member, or system), participant_id, contact_id, workspace_user_id, role, parts, attachments, created_at.
conversation_analysisconversation.analyzedid 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.
suggestionsuggestion.createdid, conversation_id, kind, title, observation, proposed_improvement, labels, created_at.
contactcontact.*id, name, email, phone, metadata, created_at, updated_at.
submissionlead.created, submission.createdid, action_id, action_key, action_kind, conversation_id, contact_id, data (keyed by your form's field keys), created_at.
ticketticket.*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.
agentagent.*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_runtraining_run.*id, agent_version_id, trigger, status, requested_at, started_at, completed_at, error_code, error_message, usage.
data_sourcedata_source.*id, source_type, name, status, error, updated_at.
deploymentdeployment.*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 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 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.

Next steps