Webhooks for Application Events

Webhooks let Bead notify your system when important events occur on a merchant onboarding application.

Instead of relying only on repeated polling, your server receives an HTTP POST when an application reaches a meaningful lifecycle moment.

Use onboarding webhooks when you want to:

• keep your own merchant records in sync with application progress

• trigger internal workflows when an application is signed, reviewed, or boarded

• notify internal teams when onboarding activity requires follow-up

• reduce repeated polling against the Get Status endpoint

• support operational dashboards and reconciliation workflows

Onboarding webhooks are configured at the partner level. Once configured, Bead sends onboarding-related events for applications associated with that partner.

How onboarding webhooks work

A typical webhook workflow is:

1. You create or manage onboarding applications under a partner.

2. You configure a partner-level onboarding webhook endpoint.

3. Bead sends an event to your endpoint when an application lifecycle event occurs.

4. Your system validates the request, records the event, and updates internal state.

5. If you need the full current application state, call GET /merchant-onboarding/applications/{applicationId} using the applicationId from the webhook.

Webhook payloads are event notifications. They are not intended to replace the Get Status endpoint as the full source of application truth.

Supported onboarding events

Onboarding webhook configuration supports these event types:

Event type	Meaning	Recommended handling
applicationSigned	The signer completed the signing step represented by the onboarding package.	Record the event and call Get Status to confirm the current application state.
applicationReviewed	The application review step produced a review event.	Call Get Status to determine whether the application is reviewed, still needs action, or has moved forward.
merchantBoarded	The merchant has completed boarding.	Call Get Status and store onboardedMerchantId for downstream workflows.

Design your handler to tolerate additional event types in the future. New event types should not break your webhook consumer.

Configure the onboarding webhook

To receive onboarding events, configure a webhook URL for your partner.

You can register, update, or remove a partner-level webhook configuration.

Action	Endpoint
Register webhook configuration	POST /merchant-onboarding/{partnerId}/webhook
Register or update webhook configuration	PUT /merchant-onboarding/{partnerId}/webhook
Remove webhook configuration	DELETE /merchant-onboarding/{partnerId}/webhook

For most integrations, use PUT so the same command can create or update the configuration.

Endpoint

PUT /merchant-onboarding/{partnerId}/webhook

Authentication and headers

Onboarding requests use API key authentication.

X-Api-Key: {apiKey}
Content-Type: application/json
Accept: application/json

Path parameter

Parameter	Description
partnerId	Your partner identifier. The webhook configuration is stored per partner and applies to onboarding applications submitted under that partner.

Request body

Use a request body with your webhook endpoint URL and the onboarding event types you want to receive.

{
  "endpointUrl": "https://partner.example.com/webhooks/onboarding",
  "eventTypes": [
    "applicationSigned",
    "applicationReviewed",
    "merchantBoarded"
  ]
}

Field details

Field	Required	Description
endpointUrl	Yes	HTTPS URL of your server that will receive onboarding webhook callbacks.
eventTypes	Yes	List of onboarding event types to deliver to this endpoint.

Your endpointUrl should be stable, publicly reachable, HTTPS-only, and controlled by your organization.

You can call the PUT endpoint more than once to update the same partner’s webhook configuration.

Response

The response confirms the current webhook configuration.

Typical fields include:

• partnerId

• endpointUrl

• isEnabled

• webhookSecret

• eventTypes

Example response:

{
  "partnerId": "partner_123",
  "endpointUrl": "https://partner.example.com/webhooks/onboarding",
  "isEnabled": true,
  "webhookSecret": "whsec_example_secret",
  "eventTypes": [
    "applicationSigned",
    "applicationReviewed",
    "merchantBoarded"
  ]
}

Store the webhookSecret securely. Treat it as a secret and do not expose it in client-side code.

Receiving webhook events

After you configure an onboarding webhook, Bead sends HTTP POST requests to your endpointUrl when selected onboarding events occur.

High-level behavior:

• method is POST

• content type is JSON

• body contains event metadata plus a small application summary

• your endpoint should return a 2xx response when processing succeeds

Onboarding webhook payloads are intentionally lean. They are not full application records.

Use the webhook payload to:

• identify which application changed

• identify what event occurred

• correlate the event to your own merchant or partner records

• trigger follow-up actions

• decide whether to fetch the full application status

Use GET /merchant-onboarding/applications/{applicationId} when you need the full current state of the application.

Security and verification

Treat onboarding webhooks as a privileged integration path.

Recommended practices:

• use HTTPS for your webhook endpoint

• accept only POST on your webhook route

• preserve the raw request body and request headers

• validate the request body against expected fields

• use the webhookSecret from the webhook configuration for verification where your program enables signing or shared-secret verification

• optionally restrict source IPs or networks where appropriate for your environment

The exact signing or authentication mechanism may vary by environment or program. If your environment provides a signature header or specific signing format, validate that before processing the event.

Payload format

Onboarding application events use a small event envelope with top-level metadata and a nested data object.

Top-level fields

Field	Type	Description
id	string	Unique webhook event identifier.
type	string	Event type that describes what occurred.
applicationId	string	Primary onboarding application identifier.
createdAt	string	Timestamp when the event was created.
data	object	Small application summary associated with the event.

data object fields

Field	Type	Description
data.id	string	Application identifier within the nested payload. This should match applicationId.
data.merchantName	string | null	Merchant name associated with the application.
data.partnerName	string | null	Partner name associated with the application.
data.partnerId	string	Partner identifier associated with the application.
data.partnerExternalId	string | null	Your external partner reference, when available.

Example payload

Below is an example applicationSigned onboarding webhook event.

{
  "id": "evt_example_application_signed_001",
  "type": "applicationSigned",
  "applicationId": "app_example_001",
  "createdAt": "2026-03-30T20:46:15.111218Z",
  "data": {
    "id": "app_example_001",
    "merchantName": "Example Merchant",
    "partnerName": "Example Partner",
    "partnerId": "partner_example_001",
    "partnerExternalId": "example-partner-001"
  }
}

Field guidance

id

This is the webhook event identifier. Use it as the primary event-level idempotency key whenever possible.

type

This tells you what happened.

Supported onboarding event types include:

• applicationSigned

• applicationReviewed

• merchantBoarded

Use type as the primary event classifier, but do not treat it as the complete application state. Call Get Status when your system needs to know the current application status.

applicationId

This is the primary application correlation key.

Use it to:

• link the webhook to your internal onboarding record

• call Get Status for full application detail

• reconcile lifecycle changes over time

• support internal dashboards and support workflows

createdAt

This is the event timestamp. It is useful for event ordering, auditing, and deduplication.

Do not rely on events arriving in strict chronological order. Use createdAt for audit context and call Get Status to confirm the current application state.

data

This object contains a lightweight application summary.

It is useful for:

• displaying a readable merchant or partner name in logs and dashboards

• routing to the correct partner context

• correlating internal references without requiring an immediate follow-up API call

Event handling expectations

At minimum, your webhook handler should store:

• id

• type

• applicationId

• createdAt

In most integrations, you should also store:

• data.partnerId

• data.partnerExternalId

• data.merchantName

• the raw request body

• the request headers

• your processing result

Treat the payload as an event trigger, not a source of full application truth.

Recommended processing model

A recommended webhook processing model is:

1. Receive the request.

2. Preserve the raw request body and headers.

3. Verify authenticity using your configured webhook security model.

4. Parse the JSON payload.

5. Use id as the event identifier and applicationId as the application correlation key.

6. Apply idempotent processing so duplicate deliveries do not create duplicate actions.

7. Call Get Status when you need the full current application state.

8. Update your internal systems.

9. Return a 2xx response quickly.

Idempotency and duplicate handling

Treat webhook delivery as at least once.

A good idempotent processing strategy is:

• primary event key: id

• fallback key: applicationId + type + createdAt

Your system should be able to safely ignore or reprocess duplicate webhook deliveries without creating duplicate tasks, records, or notifications.

Using webhooks with Get Status

Webhooks and Get Status work best together.

Use the webhook to:

• detect that something changed

• know which application changed

• route the event internally

• trigger follow-up workflows

Use Get Status to:

• retrieve the current full application state

• confirm the latest status before irreversible actions

• check for onboardedMerchantId after merchantBoarded

• surface complete details in your portal or internal tools

This is especially important because onboarding webhook events are intentionally smaller than the full application record.

Mapping events to application status

Webhook event types and application statuses are related, but they are not the same thing.

Webhook event	Related status context	Recommended action
applicationSigned	Often associated with signer completion and statuses such as signed, reviewing, or later states.	Call Get Status and update your internal record using the returned status.
applicationReviewed	Often associated with review completion and statuses such as reviewed, boarding, withdrawn, or rejected.	Call Get Status and determine the next operational step from the current status.
merchantBoarded	Usually associated with the boarded status and presence of onboardedMerchantId.	Call Get Status, store onboardedMerchantId, and proceed with downstream merchant workflows.

Do not assume the webhook event alone contains the final current status. Always call Get Status when the next action depends on the exact current application state.

Using webhooks with manual risk and review workflows

Webhooks also complement manual risk, review, and operations workflows.

A common pattern is:

1. receive an onboarding webhook event

2. call Get Status for the latest state

3. surface the current state to your operations team or merchant-facing portal

4. take the next internal action based on the returned status and any onboarding exceptions

This is especially useful when an application needs review, follow-up, or operational investigation.

Testing your onboarding webhook

Before going live:

1. Implement a simple listener endpoint that logs incoming requests and returns 200 OK.

2. Configure your Sandbox partner to use that endpoint.

3. Include the event types you want to test.

4. Submit test onboarding applications.

5. Capture real webhook events.

6. Confirm your processing is idempotent.

7. Confirm your system can use applicationId to fetch full application state.

Recommended events to test over time:

• applicationSigned

• applicationReviewed

• merchantBoarded

For a complete Sandbox workflow test, use Test the Full Onboarding Workflow in Sandbox and confirm your webhook listener receives the expected lifecycle events as the application moves through signing, review, and boarding.

Troubleshooting

I am not receiving onboarding webhook events

Check:

• the webhook is configured on the expected partnerId

• the applications were created under that partner

• the configured eventTypes include the event you expect to receive

• your endpoint is publicly reachable

• your endpoint accepts POST

• your endpoint returns a 2xx response

• your endpoint does not time out

I received a webhook but need more application detail

Use applicationId and call:

GET /merchant-onboarding/applications/{applicationId}

I am unsure how to verify authenticity

Use the configured webhookSecret and your program’s signing or shared-secret verification method.

If your environment uses a specific header or signature format, validate that before processing.

The webhook payload does not include everything I need

This is expected. The onboarding webhook payload is designed as a lightweight event notification.

Use it to trigger follow-up logic, then call Get Status when you need the full application record.

I received the same webhook more than once

This can happen with at-least-once webhook delivery.

Use id as your event-level idempotency key. Your system should safely ignore duplicates or reprocess them without creating duplicate tasks, records, emails, or status changes.

I received an event type I do not recognize

Store the event, avoid failing your handler, and return 2xx if the request is otherwise valid.

Then call Get Status using applicationId to determine the current application state.

Best practices

• Treat onboarding webhook events as event notifications, not full application records.

• Configure only the event types your system is prepared to process.

• Use id as the primary event identifier.

• Use applicationId as the primary application correlation key.

• Return a 2xx response quickly.

• Make your consumer idempotent.

• Keep your webhook endpoint HTTPS-only.

• Store webhookSecret securely.

• Capture and test real Sandbox events before Production.

• Call Get Status before taking irreversible or operationally sensitive actions.

• Design your handler to tolerate new event types or additional fields in the future.

Related pages

• Submit Application

• Fee Configuration for Onboarding Applications

• Application Attachments

• Test the Full Onboarding Workflow in Sandbox

• Get Status

• Resend Application

• Sample Payload