Webhooks

Bitwage sends webhook events as HTTP POST requests to your configured endpoint when specific events occur.

Setting up your webhook

Go to the Webhooks tab in your Bitwage Business Account settings.
Create and manage webhooks.
Configure your endpoint URL and note the signing secret.

Webhook events

Event	Description
`payroll.created`	A company created a payroll.
`user.create_user`	A new user was created.
`user.payment_status_update`	A user’s payment status changed.
`user.kyc_status_update`	A user’s KYC verification status changed.
`user.funding_account_status`	A user’s funding account status changed.

Webhook format

All webhooks are sent as POST requests with a JSON body:

{
  "data": { ... },
  "event": "event_name"
}

User KYC status update

Sent when a user’s KYC verification status changes.

{
  "event": "user.kyc_status_update",
  "data": {
    "user_id": "1234567890",
    "kyc_verification_status": "approved"
  }
}

User payment status update

Sent when a user’s payment status changes. Includes the full payment object with allocation outputs. For merchant claim payments, data.claim_id contains the claim ID. For non-claim payments, this field can be null.

{
  "event": "user.payment_status_update",
  "data": {
    "subpayroll_id": "9876543210",
    "claim_id": "claim_1234567890",
    "user_id": "1234567890",
    "company_id": "company_1234567890",
    "status": "released",
    "payment": {
      "subpayroll_id": "9876543210",
      "received": true,
      "released": true,
      "fulfilled": false,
      "outputs": [
        {
          "input_currency": "USD",
          "output_currency": "BTC",
          "volume_input_in_input_currency": 500.00,
          "volume_output_in_output_currency": 0.005,
          "fees": 2.50,
          "tx_hash": "abc123..."
        }
      ]
    }
  }
}

Payroll status webhook payloads do not include a top-level claim_id. For claim-linked payrolls, the related claim appears as invoice_id on each payment item and in the payroll-level invoice_ids list.

Validating webhook signatures

It is strongly recommended to verify webhook signatures in production. Webhooks include an x-bitwage-signature HTTP header containing a SHA256 HMAC signature of the payload.

Verification steps

Get the raw request body as a UTF-8 string.
Compute the HMAC-SHA256 using your signing secret.
Compare the computed signature with the x-bitwage-signature header.

Python example

import hmac
import hashlib
import json
from decimal import Decimal
from datetime import datetime, date


def default(obj):
    if isinstance(obj, Decimal):
        return str(obj)
    if isinstance(obj, (datetime, date)):
        return obj.isoformat()


signing_secret = "whsec_..."  # from your webhook endpoint in the app
signature_header = request.headers.get("BITWAGE_SIGNATURE")
content = request.get_json(silent=True)
bodystr = json.dumps(
    json.loads(content),
    cls=json.JSONEncoder,
    ensure_ascii=False,
    default=default,
)
message = endpoint_url + bodystr
expected_sig = hmac.new(
    signing_secret.encode("utf-8"),
    message.encode("utf-8"),
    hashlib.sha256,
).hexdigest()

if expected_sig == signature_header:
    print("SIGNATURE_VERIFIED")

Best practices

Return a 200 status promptly to acknowledge receipt. Process the event asynchronously if needed.
Handle duplicates by checking for duplicate event IDs. Bitwage may retry delivery if your endpoint doesn’t respond with a 200.
Verify signatures to ensure webhooks are genuinely from Bitwage.

Getting started

Concepts

Setting up your webhook

Webhook events

Webhook format

User KYC status update

User payment status update

Validating webhook signatures

Verification steps

Python example

Best practices

​Setting up your webhook

​Webhook events

​Webhook format

​User KYC status update

​User payment status update

​Validating webhook signatures

​Verification steps

​Python example

​Best practices

Setting up your webhook

Webhook events

Webhook format

User KYC status update

User payment status update

Validating webhook signatures

Verification steps

Python example

Best practices