Webhooks

Overview

Webhooks allow your system to receive near real-time updates when important events happen in Onboard, without polling the API.

Endpoint Requirements

• Expose an HTTPS endpoint.
• Accept POST requests with JSON payloads.
• Verify request authenticity before processing.
• Return 2xx quickly and process work asynchronously when possible.

Example Webhook Request

POST /webhooks/onboard HTTP/1.1
Content-Type: application/json
x-onboard-hmac-sha256: 9f0f2d2f...
x-onboard-account-uuid: 2b4f87e8-4da9-4a79-95f7-0f55a2ea9d4c
x-onboard-webhook-subscription-id: 31
x-onboard-webhook-event-uuid: a2f4bcb0-c4bb-4fbb-b47d-6d4b13db4f3e

Example Event Payload

{
  "version": "0.1",
  "created_at": "2026-05-06T19:52:11Z",
  "event_uuid": "a2f4bcb0-c4bb-4fbb-b47d-6d4b13db4f3e",
  "event_type": "map-created",
  "target": "https://example.com/webhooks/onboard",
  "onboarder_company_id": 8,
  "data": {
    "id": 415,
    "uuid": "4acfdba6-6d09-4f92-9cd5-4f34f39e8432",
    "name": "Customer Onboarding",
    "status": "active"
  }
}

Payload Field Types

• version: string
• created_at: datetime (UTC, ISO-like format)
• event_uuid: UUID string
• event_type: string enum (see supported event types below)
• target: URL string
• onboarder_company_id: integer
• data: object (shape varies by event type)

Supported Event Types

• map-created
• map-updated
• map-status-updated
• map-owner-updated
• map-custom-field-updated
• map-task-created
• map-task-updated
• map-task-assignee-updated
• map-task-due-date-updated
• map-task-status-updated
• map-section-completed
• customer-created
• customer-updated
• customer-custom-field-updated
• discussion-message-created
• team-member-created
• variable-created
• global-task-created
• workflow-completed
• custom-form-submitted

Event Processing

For each webhook event:

1. Validate the request and payload.
2. Record the event ID for idempotency tracking.
3. Apply your business logic.
4. Return success only after the event is safely accepted.

Reliability and Retries

Webhook deliveries can be retried. Your handler should be idempotent so repeated delivery of the same event does not create duplicate side effects.

Idempotency Example

const eventUuid = headers.get("x-onboard-webhook-event-uuid");
if (!eventUuid) return new Response("missing event uuid", { status: 400 });

if (await alreadyProcessed(eventUuid)) {
  return new Response("ok", { status: 200 });
}

await processEvent(payload);
await markProcessed(eventUuid);
return new Response("ok", { status: 200 });

Security

• Keep webhook endpoints server-side only.
• Verify authenticity before executing logic.
• Log failed deliveries with enough context for debugging.

Local Testing

• Use a staging endpoint before production rollout.
• Trigger known events and verify payload handling.
• Confirm retry behavior by forcing transient failures.