Overview

Onboard → your servers: when you configure a webhook URL, Onboard sends HTTP POST requests to that URL with JSON payloads when subscribed events occur. Your application receives those calls, so you get near real-time updates when important events happen in Onboard—without polling the API.

Delivery path

How Onboard reaches your HTTPS endpoint

When an event fires, Onboard issues a signed POST to the URL you configured. The animated border traces that delivery path: platform → network → you.

1. Event in OnboardA supported change occurs (for example map-created).
2. Signed deliveryJSON body plus headers such as x-onboard-hmac-sha256.
3. Your endpoint
Verify the signature, return a 2xx response quickly, then run your logic asynchronously when possible. Keep processing idempotent for retries.

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.

See the Security checklist for webhook-related checks alongside the rest of your integration. For verifying signatures, see HMAC validation.

Example Webhook Request

Onboard sends a POST like the following to the HTTPS URL you configured (path here is illustrative—use your own endpoint path):

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:

Validate the request and payload.
Record the event ID for idempotency tracking.
Apply your business logic.
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.

Webhooks