Webhooks

The platform sends webhook notifications via POST requests to your configured endpoint. Webhooks are signed with a Signature Token for security verification.

You can get your Signature Token on the Settings → Tokens page.

Setup

Configure your webhook URL through the dashboard (Settings → Tokens → Webhook URL) or via the Set Webhook URL endpoint.

Signature Verification

Every webhook contains a Signature header generated using HMAC-SHA512 with your Secret Key. Always verify this signature to ensure the webhook is authentic.

How to verify on your side

1. Receive the webhook POST request
2. Read the Signature header value
3. Hash the request body using your Secret Key with the generateWebhookSignature function shown on the right
4. Compare your computed hash with the Signature header value

Security

We recommend verifying every webhook. For each request, hash the payload using your Secret Key and compare it with the Signature header. This prevents attackers from sending fake webhooks.

Webhook Types

Three categories of webhooks are sent, each with its own payload structure:

• Invoice Webhooks — status updates for invoice payments
• Withdrawal Webhooks — withdrawal processing updates
• Static Address Deposit Webhooks — deposits to static addresses

HOW Paidlys SENDS WEBHOOKS

private async sendWebhookNotification(
    webhookUrl: string,
    payload: any,
    secretKey: string,
  ): Promise<void> {
    const signature = this.generateWebhookSignature(secretKey, payload);
    await axios.post(webhookUrl, payload, {
      headers: {
        'Content-Type': 'application/json',
        signature: signature,
      },
    });
  }

private generateWebhookSignature(secretKey: string, payload: any): string {
    const hmac = createHmac('sha512', secretKey.trim());
    hmac.update(JSON.stringify(payload));
    return hmac.digest('hex');
  }

Where secretKey is the merchant's Secret Key from Settings → Tokens page.