# Webhooks

Receive real-time notifications about merchant onboarding and lifecycle events.

Webhooks enable your platform to receive real-time notifications when merchant onboarding and account lifecycle events occur within Deluxe.

For platform integrations, webhooks provide the event stream needed to synchronize merchant data, maintain account mappings, and automate onboarding workflows across multiple merchants.

These platform-specific events are intended for ISVs and partners that manage portfolios of merchants.

### Why Platform Webhooks Matter

Unlike a single-merchant integration, a platform integration typically manages many merchant accounts.

Platform webhooks help you:

- Automatically detect when new merchants are provisioned.
- Synchronize merchant profile updates across your platform.
- Maintain merchant-to-platform account mappings.
- Capture newly provisioned device and account information.
- Route events to the appropriate merchant within your application.


### Platform Webhook Events

The following webhook events are specific to Deluxe for Platforms use cases.

| Event | Description | Typical Use Cases |
|  --- | --- | --- |
| Merchant Boarded | Sent when a merchant is successfully boarded into the Deluxe Payments Platform. Includes merchant information, credentials, payment enablements, and associated devices. | Create merchant records, save merchant identifiers, store access credentials, and map devices to merchant locations. |
| Merchant Updated | Sent when merchant information changes. Includes the fields that changed and their previous and current values. | Synchronize merchant profile updates, refresh configuration data, and update internal merchant records. |


### Multi-Merchant Event Handling

In a platform environment, webhook events are delivered to a shared platform endpoint rather than individual merchant endpoints.

Your application is responsible for:

1. Receiving webhook events.
2. Identifying the merchant associated with the event.
3. Routing the event to the correct merchant record.
4. Updating platform data and workflows accordingly.


The multi-merchant event handling model shows how a webhook generated by the Deluxe Platform is received through shared merchant endpoints. The platform identifies the merchant associated with the event, routes the event to the appropriate merchant, and uses the event information to update platform data and workflows.

**Generate Webhook Event**
An event occurs within the Deluxe Platform that generates a webhook.

**Identify Associated Merchant**
The shared merchant endpoint uses the webhook event information to identify the merchant associated with the event.

**Route Event to Merchant**
Route the event to the appropriate merchant, such as Merchant A, Merchant B, or Merchant C.

**Update Platform Data and Workflows**
Use the merchant-specific event to update the appropriate platform data and workflows.

Platforms should maintain merchant identifiers and account mappings so incoming webhook events can be associated with the correct merchant within the platform.

### Device Provisioning Considerations

For device-enabled merchants, device information is delivered as part of merchant onboarding events.

Platforms should persist the provided Device ID and associate it with the appropriate:

- Merchant
- Location


This enables future device management and cloud-to-device payment workflows.

### Implementation

This page focuses on platform-specific webhook considerations.

Refer to complete [Webhook Implementation](/products/merchant-services/developer-resources/developer-guide/webhook-integration) guidance, for:

- Creating a webhook endpoint
- Registering endpoints
- Subscribing to events
- Webhook security and signature validation
- Retry behavior and duplicate handling
- Testing and production deployment


### Related Resources

Implement Merchant Onboarding
Build merchant onboarding workflows using Deluxe platform capabilities and APIs.

Merchant Onboarding API
Review endpoints, schemas, objects, and API operations.

Merchant Onboarding
Understand how merchant onboarding events fit into the merchant lifecycle.