Webhooks for Application Events

Register an onboarding webhook for a partnerId to receive application events as they happen. Content includes registration and deletion examples, authentication options, webhook secret guidance, and event type configuration.

Overview

When a webhook is registered for a partner, Bead sends HTTP callbacks to your endpoint when onboarding milestones occur. This keeps your system in sync without polling.

Common use cases:

• Update your onboarding status view in near real time

• Trigger internal workflows when an application progresses

• Reduce polling and support tickets by relying on event callbacks

Authentication

Requests to register or delete a webhook can be authenticated using either method below.

Preferred standard going forward:

• Onboarding API key in X-Api-Key

Legacy support during documentation cleanup:

• Bearer token in Authorization

Preferred: API key

Use your onboarding API key in the X-Api-Key header.

-H 'X-Api-Key: <ONBOARDING_API_KEY>'

Legacy: Bearer token

Use an access token in the Authorization header.

-H 'Authorization: Bearer <ACCESS_TOKEN>'

Register a webhook

Registers the webhook destination URL and the event types to receive for a specific partnerId.

POST /merchant-onboarding/{partnerId}/webhook

Request body

{
  "endpointUrl": "<YOUR_WEBHOOK_URL>",
  "eventTypes": [
    "applicationSigned",
    "applicationReviewed",
    "merchantBoarded"
  ]
}

Field notes

• endpointUrl Public HTTPS endpoint that can receive webhook POSTs. Use a URL your system controls, for example:

  • https://example.com/webhooks/bead/onboarding

• eventTypes List of onboarding events your endpoint should receive.

Example request (API key)

curl -X 'POST' \
  'https://api.test.devs.beadpay.io/merchant-onboarding/<PARTNER_ID>/webhook' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'X-Api-Key: <ONBOARDING_API_KEY>' \
  -d '{
    "endpointUrl": "<YOUR_WEBHOOK_URL>",
    "eventTypes": [
      "applicationSigned",
      "applicationReviewed",
      "merchantBoarded"
    ]
  }'

Example request (Bearer token)

curl -X 'POST' \
  'https://api.test.devs.beadpay.io/merchant-onboarding/<PARTNER_ID>/webhook' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
    "endpointUrl": "<YOUR_WEBHOOK_URL>",
    "eventTypes": [
      "applicationSigned",
      "applicationReviewed",
      "merchantBoarded"
    ]
  }'

Example response

The response includes the configured endpoint URL, enabled status, selected event types, and may include a webhook secret.

{
  "partnerId": "<PARTNER_ID>",
  "endpointUrl": "<YOUR_WEBHOOK_URL>",
  "isEnabled": true,
  "webhookSecret": "<WEBHOOK_SECRET>",
  "eventTypes": [
    "applicationSigned",
    "applicationReviewed",
    "merchantBoarded"
  ]
}

Webhook secret guidance

The register response may include webhookSecret. If returned, treat it like a password.

Recommended practices:

• Store it securely using a secrets manager or encrypted storage.

• Never commit it to source control.

• Never expose it in client-side code.

• Do not log it. If logging is needed, log only that a secret exists, not the secret value.

• Store it immediately after registration.

Webhook requests are expected to include a signature that can be validated using the webhook secret. Verify the signature before processing the payload.

If webhookSecret is not returned, proceed with registration and event handling. Do not assume signature verification is available until a secret is issued for your partner.

Delete a webhook

Deletes the webhook configuration for a specific partnerId.

DELETE /merchant-onboarding/{partnerId}/webhook

Example request (API key)

curl -X 'DELETE' \
  'https://api.test.devs.beadpay.io/merchant-onboarding/<PARTNER_ID>/webhook' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: <ONBOARDING_API_KEY>'

Example request (Bearer token)

curl -X 'DELETE' \
  'https://api.test.devs.beadpay.io/merchant-onboarding/<PARTNER_ID>/webhook' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Event types

Event types control which onboarding milestones are delivered to your endpoint.

Example event types:

• applicationSigned

• applicationReviewed

• merchantBoarded

Use only the event types supported by your current API spec. If you request an unsupported value, the registration call may fail validation.

Delivery expectations

General guidance for webhook endpoints:

• Use HTTPS.

• Respond with HTTP 2xx quickly to acknowledge receipt.

• Process payloads asynchronously if your workflow is heavy.

• Implement idempotency on your side in case an event is delivered more than once.

Troubleshooting

401 Unauthorized or 403 Forbidden

Common causes:

• Missing X-Api-Key or Authorization header

• Incorrect key type, using a payments key instead of an onboarding key

• partnerId is not in scope for the provided credential

Not receiving events

Common causes:

• endpointUrl is not publicly reachable from the internet

• TLS certificate issues

• Endpoint responds with non-2xx and the event is not accepted

• Webhook was never registered for the partnerId you are testing

Signature verification fails

Common causes:

• Using the wrong webhook secret

• Body was modified before verification (whitespace changes, JSON reserialization)

• Verifying against a parsed object instead of the raw request body

Related pages

• Sample Payload

• Webhooks and error codes