Skip to Content
WebhooksOverview & Listener Integration

Webhooks Overview & Listener Integration

Onbo Webhooks deliver real-time notifications directly to your server whenever an onboarding job completes automated decisioning or human manual review.

Webhooks eliminate the need to poll Onbo APIs and allow your application backend to trigger downstream business workflows (such as account creation, employee activation, or risk flags) instantly.

Supported Lifecycle Events

Onbo supports two core lifecycle event types:

Event TypeTrigger PointOutcomes Carried
application.decisionFired when automated processing finishes for a job.APPROVED, REVIEW, DECLINED, ERROR, EXISTING_CUSTOMER
application.reviewedFired when an operations agent completes a human review.APPROVED, DECLINED, SUSPICIOUS

Key Event Characteristics

  • Event Identifier (event.id): Every webhook delivery carries a unique ULID event identifier in event.id. This identifier remains constant across retries for the same event dispatch.
  • Multiple Events per Job: An onboarding job that requires human review will fire an application.decision event (carrying outcome REVIEW), followed later by an application.reviewed event once reviewed.
  • Self-Contained Payloads: Both event types carry the complete application state, personal details, document URN references, and verification results. You do not need to stitch multiple webhooks together to inspect results — application.reviewed is a full payload plus reviewDetails, not a delta against the decision event.

Client Listener Requirements

Your webhook listener is an HTTPS endpoint hosted on your server infrastructure that receives HTTP POST notifications from Onbo.

Endpoint Requirements

  1. HTTPS Protocol: Your endpoint must be accessible over HTTPS with a valid TLS certificate. Plain HTTP endpoints are rejected.
  2. HTTP Method: Must accept POST requests.
  3. Content-Type: Requests carry Content-Type: application/json.
  4. Response Time: Your server must respond within 15 seconds (default timeout).
  5. Success Status Code: Your server must respond with a 2xx HTTP status code (e.g. 200 OK or 204 No Content) to acknowledge receipt.

Delivery Guarantees & Retries

Onbo processes outbound webhooks through a resilient queue manager providing at-least-once delivery guarantees.

Retries & Exponential Backoff

If your listener endpoint is unreachable, times out (> 15 seconds), or returns a non-2xx status code (e.g. 500 Server Error, 503 Service Unavailable, 404 Not Found), Onbo automatically queues retries with exponential backoff:

  • Maximum Retries: Up to 10 retry attempts by default.
  • Circuit Breaker: If your endpoint consistently fails across multiple events, a per-host circuit breaker protects your endpoint from traffic overload while flagging delivery failures in your Onbo Dashboard.

Idempotency Guidelines for Listeners

Because webhooks use at-least-once delivery, network glitches or transient timeouts may cause your listener to receive the same event notification more than once.

Best practices for handling duplicate deliveries:

  1. Track Processed Event IDs: Store event.id from the payload envelope in your database upon receipt.
  2. Deduplicate before Processing: Before processing an incoming webhook, verify whether event.id has already been handled. If already processed, immediately return 200 OK without re-running business logic.
  3. Job State Ordering: Check event.occurredAt or compare applicationDetails.status to ensure out-of-order retries do not overwrite newer state changes in your application. Compare the status case-insensitively — it is carried verbatim, and its casing varies by how the state was reached.

Listener Security & Authentication

Onbo supports two auth modes for securing webhook deliveries:

When configured with HMAC authentication, Onbo includes an X-IdMission-Signature header with every request:

X-IdMission-Signature: t=1756500000,kid=whsec_a1b2c3d4,v1=9f8e7d6c5b4a...

Your server verifies the signature using your secret key before processing the payload. See Verifying Signatures for the full verification procedure.

2. Custom Extra Headers

If your API gateway or webhook receiver requires static tokens, you can configure custom static headers in the Onbo Dashboard (e.g., Authorization: Bearer <your_secret_token> or X-Custom-Auth: <secret>).

Snapshot API Fallback

If webhooks are temporarily disabled, unconfigured, or failing due to listener downtime, your backend can pull full job data at any time via the Get Job Data API:

POST https://portal.idmission.com/api/get-job-data
Content-Type: application/json
X-Api-Key-Id: urn:apikeysv1:prod:region:company:YOUR_KEY_UUID
X-Api-Key-Secret: YOUR_API_KEY_SECRET
 
{
  "jobId": "019fd6b7-3def-7ece-bd47-788508d3424d"
}

The response body from get-job-data is identical to the webhook payload format, excluding the top-level event envelope object. See Get Job Data API for details.

Next Steps

Last updated on
Get Job DataVerifying Signatures