Receive webhooks

Webhooks are how you hear that a proposal was accepted or an eForm was submitted. Polling list endpoints will not tell you those moments reliably, and it will burn your rate limit.

1. Ask which events exist

GET /api/v1/webhooks/events returns a JSON array of event keys, for example proposal.accepted and eform.submitted. Subscribe only to keys in that list. The list is the contract. Do not hard-code a key you have not seen there.

Event	Fires when
`proposal.accepted`	Every required signature on the proposal is complete
`eform.submitted`	The recipient submits the eForm

proposal.accepted does not fire when you send the proposal. eform.submitted does not fire when you send the form. POST /api/v1/webhooks needs write access. One row is one event. To receive both events at the same URL, create two subscriptions.

{
  "hookUrl": "https://example.com/webhooks/onboardme",
  "webhookEvent": "proposal.accepted",
  "webhookName": "Proposal accepted"
}

hookUrl is your HTTPS endpoint. targetUrl is accepted as an alias for Zapier-style callers. Send one of them. webhookSecret is optional. Omit it and OnboardMe generates one. The 201 returns id and webhookSecret once. Store the secret in your own vault before you respond 200 to your user. A later list of subscriptions does not show it again. If you lose it, unsubscribe and subscribe again.

3. Verify every delivery

OnboardMe POSTs JSON to hookUrl and sets:

Header	Use
`X-Om-Event`	Event key, such as `proposal.accepted`
`X-Om-Event-Id`	Unique delivery id. Your idempotency key
`X-Om-Timestamp`	Unix time used in the signature
`X-Om-Signature`	`sha256=` plus lowercase hex HMAC

The signature is HMAC-SHA256 of the string:

{X-Om-Timestamp}.{rawBody}

rawBody is the exact bytes you received, before JSON parsing and before any framework re-serialises the object. A parsed-and-reprinted body will not match.

const crypto = require("crypto");

function verifyOnboardMe(rawBody, headers, secret) {
  const timestamp = headers["x-om-timestamp"];
  const signature = headers["x-om-signature"];
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature || "");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;
  return true;
}

Reject anything that fails the comparison. Then reject timestamps outside a few minutes of your clock so a captured body cannot be replayed later. Compare in UTC.

4. Dedupe, then do the work

Store X-Om-Event-Id. If you have already processed that id, return 200 and stop. OnboardMe retries when your endpoint is slow or returns an error, and a retry is the same event id with the same body. Return 2xx quickly. Download PDFs, create bills, or call back into the API after you have persisted the event id, or from a queue. Doing that work inside the request is how you time out and get a second delivery. The JSON body is the delivery for that event. Camel-case fields match the REST API. proposal.accepted (schemaVersion 4):

Field	Meaning
`eventId`	Same value as `X-Om-Event-Id`
`eventType`	`proposal.accepted`
`occurredAtUtc`	When the last required signature completed
`engagementKey`	Load `GET /api/v1/proposals/{key}`
`name`, `refNo`	Proposal name and reference
`proposalUrl`	Link to the accepted proposal
`allSignaturesComplete`	True on this event
`signers`	Who signed
`clients`	`entityKey`, `name`, `email`, `isPrimaryClient`
`acceptedServices`	Services the client accepted
`billing`	`billingEnabled`, `requestPaymentDetails`, `invoices`, and `recurringBilling`
`onboardingKey`	Set when acceptance also created an onboarding
`packageChosen`, `chosenPackageName`, `chosenPackagePrice`	Set when the client picked a package

eform.submitted (schemaVersion 1):

Field	Meaning
`formKey`	The form you stored when you sent it
`formName`	Template name shown to the recipient
`submittedOn`	When they submitted
`recipient`	`name` and `email`
`entityKey`	The client, when the form was sent to a stored entity. Null for an ad-hoc recipient
`formReviewUrl`	Where staff review the submission

Do not treat either body as a full proposal or a full form definition. Load the REST resource when you need line items, files, or status that the event does not include.

5. Prove the endpoint, then remove it

POST /api/v1/webhooks/{id}/test sends a signed test delivery to that subscription. Verify your HMAC code against the test before you go live. The test is not a real proposal.accepted. DELETE /api/v1/webhooks/{id} removes the subscription. Use the id from the 201, not the event name.

Production checklist

HTTPS only, and a URL you control. A request-bin left over from development will receive client names.
One secret per subscription, stored outside source control.
Signature checked before you parse the body for business logic.
X-Om-Event-Id unique index so retries are harmless.
Handlers for the events you subscribed to, and a default that records and ignores anything else so a new event key cannot crash the endpoint.

Webhook reference

Events, subscribe, unsubscribe, and the test delivery.

Core Concepts

Guides

1. Ask which events exist

3. Verify every delivery

4. Dedupe, then do the work

5. Prove the endpoint, then remove it

Production checklist

Webhook reference

​1. Ask which events exist

​2. Subscribe once per event

​3. Verify every delivery

​4. Dedupe, then do the work

​5. Prove the endpoint, then remove it

​Production checklist

Webhook reference

1. Ask which events exist

2. Subscribe once per event

3. Verify every delivery

4. Dedupe, then do the work

5. Prove the endpoint, then remove it

Production checklist