Webhooks allow LedgerBlock to notify your application when an event occurs in the LedgerBlock system.

Instead of continuously polling an API endpoint to determine whether an operation has changed, your application can receive notifications from LedgerBlock through a webhook endpoint that you provide.

LedgerBlock supports webhook notifications for areas including collections and payouts.

Webhook Algorithm

LedgerBlock uses HMAC-SHA512 to generate webhook signatures.

The signature is provided in the following request header:

x-ledgerblock-signature: <signature>

Your application should use this signature to verify that the webhook request was generated by LedgerBlock before processing the notification.

Signature Header

The webhook signature should always be verified before your application processes the webhook payload.

Webhook Verification

Webhook verification ensures that your application can validate an incoming webhook before trusting the data contained in the request.

When LedgerBlock sends a webhook to your configured endpoint, your application should:

1. Receive the webhook request.
2. Retrieve the x-ledgerblock-signature header.
3. Generate the expected HMAC-SHA512 signature using the verification method provided for your integration.
4. Compare the generated signature with the signature received from LedgerBlock.
5. Process the webhook only when the signatures match.
6. Reject the request when the signature cannot be verified.

Verification Flow

LedgerBlock
     |
     | Webhook request
     | + x-ledgerblock-signature
     v
Your Webhook Endpoint
     |
     | Generate expected HMAC-SHA512 signature
     v
Compare Signatures
     |
     +---- Match ------> Process Webhook
     |
     +---- No Match ---> Reject Webhook

Important

Do not trust a webhook simply because it was received by your endpoint.

Always verify the x-ledgerblock-signature before processing the event.

Your webhook verification implementation should also ensure that the payload used to generate the expected signature is handled exactly as required by LedgerBlock. Changes to the request body before verification can result in a signature mismatch.

Webhook Structures

LedgerBlock webhook notifications are delivered as HTTP requests to your configured webhook endpoint.

Webhook notifications currently cover areas including:

• Collections
• Payouts

The exact event and payload structure depends on the webhook being delivered.

Collection Webhooks

Collection webhooks are used to notify your application about events relating to collections.

A collection webhook contains the event information and associated collection data provided by LedgerBlock.

Your application should use the webhook payload to determine the relevant transaction and update its internal state accordingly.

Payout Webhooks

Payout webhooks are used to notify your application about events relating to payouts.

A payout webhook contains the event information and associated payout data provided by LedgerBlock.

Your application should use the webhook payload to determine the relevant payout and update its internal state accordingly.

Webhook Endpoint

Your webhook endpoint should be a server-side URL capable of receiving HTTP requests from LedgerBlock.

For example:

https://your-domain.com/webhooks/ledgerblock

The endpoint should:

1. Accept incoming webhook requests.
2. Read the request headers.
3. Retrieve the x-ledgerblock-signature header.
4. Verify the webhook signature.
5. Parse the webhook payload.
6. Process the event.
7. Return the appropriate HTTP response.

Security Recommendations

When implementing LedgerBlock webhooks:

• Always verify the x-ledgerblock-signature.
• Do not process unverified webhook requests.
• Keep webhook verification logic on your backend.
• Do not expose webhook verification credentials or secrets in client-side applications.
• Preserve the request body used for signature verification.
• Log webhook processing failures for troubleshooting without exposing sensitive information.
• Design webhook processing to safely handle repeated notifications.

Important: Webhook verification should happen before your application performs any business action based on the webhook payload.