Workflow Events and Webhooks

Harmony can notify your external systems in real time whenever important things happen inside a workflow - requests being created or updated, messages being sent, and more. These notifications are delivered as workflow events and can be forwarded to any endpoint you control via webhooks.

This article explains the event types available, the data each event carries, and how to use that data to build reliable, precise integrations.

---

How Workflow Events and Webhooks Work

When activity occurs in Harmony - such as a new request being opened or a message being sent - Harmony emits a structured event. If you have a webhook configured, Harmony sends an HTTP POST request containing the event payload to your specified endpoint.

This lets your downstream systems react immediately without polling the API, making it straightforward to:

• Sync request data to your CRM or helpdesk
• Trigger automations in third-party tools
• Build audit logs and reporting pipelines
• Filter and route activity based on context

---

Configuring Webhooks

To receive events, you need to register a webhook endpoint in your Harmony workspace settings.

1. Go to Settings and open the Integrations section.
2. Select Webhooks and click Add Webhook.
3. Enter the destination URL for your endpoint.
4. Choose the event types you want to subscribe to.
5. Save your configuration.

Harmony will begin delivering events to your endpoint immediately. Each delivery is an HTTP POST request with a JSON body and a Content-Type: application/json header.

---

Event Types

Request Lifecycle Events

Request lifecycle events fire when a request is created or updated. These are the primary events for tracking the state of work moving through your workflows.

RequestCreated

Emitted when a new request is opened. The payload includes full request metadata so your systems can immediately index or act on the new request.

RequestUpdated

Emitted whenever a request is modified - for example when its status changes, it is assigned to an agent, or it is resolved.

Resolution Details on Request Events

Both RequestCreated and RequestUpdated events now include two additional fields that tell your downstream systems how a request was resolved, without requiring any follow-up API calls:

Field	Type	Description
resolution	string or null	How the request was resolved - for example escalated, handled_by_ai, or closed_by_agent.
resolution_at	timestamp or null	The date and time at which the resolution was determined.

Both fields are optional and default to null when no resolution has been recorded yet. This means the change is fully backward-compatible - your existing integrations will continue to work without any modification.

Example payload fragment:

{
  "event": "RequestUpdated",
  "request_id": "req_01abc123",
  "status": "resolved",
  "resolution": "handled_by_ai",
  "resolution_at": "2024-06-10T14:32:00Z"
}

When a request has not yet been resolved, these fields appear as:

{
  "resolution": null,
  "resolution_at": null
}

---

Message Events

MessageCreated

Emitted whenever a new message is added to a request conversation. This event is useful for building notification systems, logging conversation history, or triggering follow-up automations based on message content.

Source Attribution with event_source

The MessageCreated event includes an event_source field that tells you exactly where the message originated. This gives you the context you need to build more precise filtering and automation logic.

Value	Description
customer	The message was sent by the end user or customer.
agent	The message was sent by a human agent.
workflow	The message was generated by an automated workflow.

Example payload fragment:

{
  "event": "MessageCreated",
  "request_id": "req_01abc123",
  "message_id": "msg_09xyz789",
  "body": "Thanks for reaching out, I'll look into this now.",
  "event_source": "agent",
  "created_at": "2024-06-10T14:33:00Z"
}

You can use event_source to, for example:

• Only forward customer messages to your CRM
• Trigger a satisfaction survey only after an agent closes a conversation
• Skip logging automated workflow messages in your audit trail

---

Payload Structure

Every event payload shares a common envelope, regardless of event type:

Field	Type	Description
event	string	The name of the event, e.g. RequestCreated.
created_at	timestamp	When the event was emitted.
request_id	string	The unique identifier of the related request.

Event-specific fields are included alongside these common fields in the same flat JSON object.

---

Reliability and Retries

Harmony expects your endpoint to respond with an HTTP 2xx status code to acknowledge successful receipt. If your endpoint returns a non-2xx response or does not respond within the timeout window, Harmony will retry delivery using an exponential back-off strategy.

To avoid processing duplicate events during retries, design your endpoint to be idempotent - that is, handling the same event more than once should produce the same result as handling it once.

---

Backward Compatibility

Harmony follows an additive-only policy for event payloads. This means:

• New fields may be added to any event at any time.
• Existing fields will not be removed or renamed without advance notice.
• Optional fields default to null when not applicable, so your integration is never broken by their absence.

You should write your event consumers to ignore unknown fields rather than treating them as errors. This keeps your integrations resilient as new capabilities are introduced.