Engage Outbound Webhooks

Engage Outbound Webhooks push real-time event notifications from Hope.Cloud's Engagement platform to downstream systems. When a subscribed engagement event occurs (a message received, a reply sent, or a Hope.Study student action), Engage delivers an HTTP POST to every configured endpoint in the organization that matches the event type.

This is the integration reference for developers building downstream consumers. Configure your endpoint URL and auth token through the Engage /integrations page, then accept and process the incoming POSTs described here.

Overview

• One HTTP POST per matching event, per webhook config.
• An organization may have any number of webhook endpoints configured.
• Events are filtered per config using an explicit event-type selection.
• Delivery is best-effort with automatic retry on transient failures (see Retry behavior).

Authentication

Each webhook request carries the Authorization header set to the token you supplied at config time:

Authorization: Bearer <your-token>

Your endpoint should validate this header and return 401 or 403 for unrecognized tokens. Those responses are treated as permanent failures (no retry). Store the token as a secret in your infrastructure.

Payload schema

Every delivery is a JSON POST:

POST <your-endpoint-url>
Content-Type: application/json
Authorization: Bearer <your-token>

Body:

{
  "event": {
    "id": "egev:A1b2C3d4E5f",
    "name": "eg.message.receive",
    "timestamp": "2026-07-01T12:34:56.789Z"
  },
  "organization": {
    "id": "egorg:X1y2Z3a4B5c"
  },
  "meta": { ... }
}

Field	Type	Description
event.id	string	Unique ID of the engagement event
event.name	string	Event type name (see Event registry)
event.timestamp	ISO 8601 string	When the event was created
organization.id	string	Hope.Cloud organization that produced the event
meta	object	Platform-specific metadata, passed through from the original event

Event registry

These are the event types selectable when configuring a webhook. Select only the events your consumer needs.

Engagement events

Event name	Description
eg.message.receive	An inbound message was received on a monitored channel
eg.message.reply	A reply was sent to a message
eg.dm.receive	An inbound direct message was received
eg.dm.reply	A reply was sent to a direct message

Hope.Study events

Event name	Description
hs.student.register	A student registered
hs.course.start	A student started a course
hs.course.finish	A student finished a course
hs.lesson.start	A student started a lesson
hs.lesson.finish	A student finished a lesson

Retry behavior

On transient failures, Engage retries up to 3 attempts total with exponential backoff and full jitter:

• Retried: network errors, timeouts, and HTTP 5xx responses.
• Not retried: HTTP 4xx responses (permanent client-side failure).
• Timeout: each attempt times out after 10 seconds.
• On final failure: the delivery attempt is logged and dropped. A structured audit log entry is written for each attempt and for the final outcome.

Your endpoint must return a 2xx status code to acknowledge successful receipt. Any non-2xx response (after retries are exhausted for 5xx) is recorded as a failure.

Setting up a webhook

1. Navigate to /integrations in the Engage app (requires the Outbound Webhooks feature to be enabled for your organization).
2. Open the Webhooks tab and click Add webhook.
3. Enter your endpoint URL (must be HTTPS in production).
4. Enter your auth token. This value is write-only: once saved, it is never shown again. Leave the field blank on future edits to keep the existing token.
5. Select the event types you want to receive from the list.
6. Save. Deliveries begin immediately for new events.

To remove a webhook, use the delete action on the config row. The config is soft-deleted; no further deliveries are made.

Endpoint requirements

• Must accept HTTP POST with Content-Type: application/json.
• Must respond with a 2xx status code within 10 seconds.
• Must validate the Authorization: Bearer header and reject unauthorized requests.
• Should be idempotent: Engage may deliver the same event more than once on retry. Use event.id to deduplicate.