Webhooks for Application Events

Webhooks allow Bead to notify your system when important events occur on a merchant onboarding application. Instead of polling the API, you can receive real-time callbacks whenever an application is created, sent, completed, declined, or otherwise updated.

Use onboarding webhooks to:

• Keep your own merchant records in sync with onboarding status

• Trigger internal workflows when an application needs more information

• Notify your teams when applications are approved or declined

• Reduce the need for periodic polling with the Get Status endpoint

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

When to use onboarding webhooks

You should configure onboarding webhooks if:

• You want near real-time updates of application status in your own systems

• You plan to automate downstream actions such as provisioning, notifications, or risk review queues

• You want to track key lifecycle moments like created, sent, completed, declined, or needs more information

If you only process a few applications and handle them manually, you may rely on the portal or the Get Status endpoint instead. For most partner integrations, onboarding webhooks are strongly recommended.

Configure the onboarding webhook

To receive onboarding events, you configure a webhook URL for each partner using the Onboarding API.

Endpoint

PUT /merchant-onboarding/{partnerId}/webhook

Path parameter

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

Authentication

• Requires a valid OAuth access token for the bead-integrator client

• Use the standard Authorization header

Headers

Authorization: Bearer {access_token}
Content-Type: application/json
Accept: application/json

Request body

Use the RegisterWebhookRequest model in the request body. The body contains your webhook endpoint URL.

Example

{
  "endpointUrl": "https://partner.example.com/webhooks/onboarding"
}

Field details

• endpointUrl

  • Required

  • HTTPS URL of your server that will receive onboarding webhook callbacks

  • Should be a stable URL that you control and that you can update or redeploy without changing the address

You can call this endpoint multiple times to update the same partner’s webhook configuration. For example, you might update the URL when moving from a sandbox listener to production, or when you change your internal routing.

Response

The API returns a RegisterWebhookResponse that confirms the current configuration.

Typical fields include:

• partnerId Partner id for which this webhook configuration applies

• endpointUrl The URL currently registered for this partner

• isEnabled Indicates whether the webhook is enabled for this partner

• webhookSecret A secret value associated with this webhook configuration that can be used to validate that callbacks originate from Bead

You should store the webhookSecret securely in your configuration or secrets management system. It is not intended to be shared with end users or exposed in client-side code.

Receiving webhook events

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

High level behavior:

• Method is POST

• Content type is JSON

• Body contains information about the onboarding application and the event that occurred, such as application identifiers, partner identifiers, status updates, and event timestamps

• Your endpoint should return a 2xx status (for example 200 OK) once it processes the event

You should design your endpoint to:

• Accept POST requests over HTTPS

• Parse the JSON body

• Validate that the request is from Bead (see the section on security and verification)

• Apply your own business logic

• Return an HTTP 2xx response when processing succeeds

If your endpoint returns non-2xx responses or times out, Bead may retry delivery according to internal retry policies for your environment.

Security and verification

You should treat onboarding webhooks as a privileged integration path and verify that incoming requests are genuinely from Bead.

Recommended practices:

• Use HTTPS for endpointUrl to protect data in transit

• Restrict accepted methods to POST on your webhook route

• Validate the request body against expected fields and structure

• Use the webhookSecret from RegisterWebhookResponse to validate callbacks where your program enables signing or shared-secret verification

• Optionally restrict the source IPs or networks allowed to call your webhook, where feasible in your environment

The exact mechanism for signing or authenticating webhook requests can vary by environment. Work with your Bead contact or refer to environment-specific guidance for header names, hash algorithms, or signature formats if those are enabled for your program.

Recommended event handling pattern

A robust handling pattern looks like this:

1. Log the raw request

   • Log headers, body, and response status for debugging and audit

   • Mask or omit sensitive fields from logs as required by your policies

2. Verify authenticity

   • Confirm that the request matches your expected webhook format

   • Verify any signatures or secrets associated with the webhook configuration

   • Reject or ignore requests that do not pass verification

3. Parse the payload

   • Extract key identifiers such as applicationId, partnerId, and any status or event fields

   • Use applicationId as the primary key to correlate with your own records

4. Apply idempotent processing

   • Use an idempotency key derived from the webhook payload (for example, combination of application id and event id or timestamp)

   • Ensure that processing the same webhook more than once does not cause duplicate actions, such as creating multiple records or sending duplicate notifications

5. Update your system

   • Update internal onboarding status for the merchant

   • Trigger downstream workflows, such as provisioning, risk review, or communication with your customer

6. Respond with 2xx

   • Return an HTTP 2xx status once you have successfully processed the event

   • Only return non-2xx when you want Bead to treat the delivery as failed and potentially retry

Using webhooks with status and feedback

Webhooks complement the Onboarding status and manual feedback APIs.

• Webhooks

  • Provide push-based notifications when important onboarding events occur

  • Let you react immediately to changes like approved, declined, or needs more information

• Get Status

  • Lets your systems fetch the full state of an application at any time

  • Useful when a user opens a screen in your portal and you want the most current data

• Manual Risk Feedback

  • Lets risk and compliance teams send feedback on an application, including requests for information

  • You can use webhooks to detect when feedback has been applied and update your own queues accordingly

A common pattern is:

1. Configure an onboarding webhook per partner using PUT /merchant-onboarding/{partnerId}/webhook

2. Subscribe your internal systems to webhook events

3. Use webhooks to detect changes and then call Get Status for the updated application to pull full details

4. Use Manual Risk Feedback to send information back into the onboarding process as needed

Testing your onboarding webhook

Before going live, you should thoroughly test your webhook integration in the sandbox environment.

Suggested steps:

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

2. Configure your sandbox partner to use that endpoint as the onboarding webhook URL

3. Submit a few test onboarding applications using both full and minimal application flows

4. Verify that:

   • Your webhook endpoint receives events for those applications

   • The payloads contain the identifiers and fields you expect to use

   • Your processing logic correctly updates your internal records and is idempotent

5. Adjust logging and error handling as needed so that operational teams can troubleshoot issues in production

Once you are satisfied with testing in sandbox, repeat the configuration for your production partner id with a production-grade endpoint, logging, and monitoring.