Overview

You can use webhooks to receive real-time HTTP callbacks when specific events occur. This enables you to automate workflows, notify your end users, and keep your platform in sync with BitGo.

As a CaaS provider, you operate at the Organization level and manage numerous child enterprises (your end users). Webhooks come in two scopes:

  • Organization Webhooks - Notifications for events that apply to your entire CaaS organization, such as organization-level policy changes or new bank accounts.
  • Enterprise Webhooks - Notifications for events specific to one of your end users, such as an end-user KYC status change or a new bank account added to an end-user enterprise.

BitGo signs all webhook notifications, enabling you to verify their authenticity.

  • Webhook Secret - When you create a webhook, you can set a secret. BitGo uses this secret to generate an HMAC-SHA256 signature.
  • Signature Header - BitGo sends the signature in the x-signature-sha256 HTTP header.
  • Verification - To verify the payload, compute your own HMAC-SHA256 signature of the raw request body using your secret and compare it to the signature in the header. This is a critical security step.

Note

You may receive multiple of the same webhook notification due to at-least-once delivery infrastructure. Always design your webhook handlers to be idempotent so you can identify duplicate notifications.

Enterprise Webhook Types

Type Triggers When
accessToken A user creates an access token.
bankAccount A user adds a bank account.
mintOrder A mint order status changes.
policyBalanceChange An enterprise policy balance changes.
reversal BitGo reverses a fiat transaction.

Organization Webhook Types

Type Triggers When
accessToken A user creates an access token.
bankAccount A user adds a bank account.
enterpriseKycState Enterprise KYC status changes.
identityStatus A user identity status changes.
idvStatus A user IDV status changes.
pendingapproval A transaction request is pending approval.
reversal BitGo reverses a fiat transaction.
tradeOrder A trade order status changes.
transfer A transfer succeeds or fails.
txRequest A transaction request changes status.
txRequestTransaction The underlying transaction of a transaction request changes state.
userKycState A user KYC verification status changes.
whitelistApproved A pending withdrawal-address whitelist request is approved.
whitelistRejected A pending withdrawal-address whitelist request is rejected.

Webhook Payload Schemas

Each webhook type returns a different JSON payload. Use these example schemas to parse and handle incoming webhook notifications.

Triggered when a user creates an access token.

{
  "userId": "59cd72485007a239fb00282a",
  "username": "user@example.com",
  "tokenCreateTime": "2024-01-15T10:30:00.000Z",
  "tokenExpireTime": "2024-01-15T18:30:00.000Z",
  "spendingLimits": "{\"txValue\":1000000,\"txValueLimit\":5000000}",
  "tokenIp": "192.168.1.100",
  "tokenIpWhitelist": ["192.168.1.0/24"],
  "tokenScope": "wallet_view_all wallet_spend_all",
  "enterpriseName": "Test Enterprise",
  "id": "59cd72485007a239fb00282b",
  "enterpriseId": "59cd72485007a239fb00282c",
  "organizationId": "59cd72485007a239fb00282d"
}

Cookbooks

Need just the steps? Expand a cookbook below to get started:

Create Webhooks (Enterprise)Open Cookbook Create Webhooks (Organization)Open Cookbook

Prerequisites

1. Create Organization Webhooks

The following example creates a webhook that notifies you whenever a user adds a bank account.

Endpoint: Create Organization Webhook

export ORGANIZATION_ID="<YOUR_ORGANIZATION_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export URL="<YOUR_WEBHOOK_URL>"
export LABEL="<YOUR_WEBHOOK_NAME>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/organization/$ORGANIZATION_ID/webhook \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "type": "bankAccount",
    "url": "'"$URL"'",
    "label": "'"$LABEL"'"
  }'
Step Result
{
  "id": "690278897328c7fc41e81887d4b76964",
  "label": "test org webhook 1",
  "created": "2025-10-29T20:26:49.286Z",
  "scope": "organization",
  "organizationId": "68f6af3f2f29893d5863bc0eaf77b3c6",
  "type": "bankAccount",
  "url": "https://webhook.site/2635918b-018b-4179-82e9-6940a0b851e0",
  "version": 1,
  "state": "active",
  "successiveFailedAttempts": 0,
  "listenToFailureStates": false,
  "txRequestStates": [],
  "txRequestTransactionStates": [],
  "identityStatus": []
}

2. (Optional) Create Webhook Secret

Create a webhook secret that enables you to verify webhook notifications. BitGo uses this secret to generate HMAC-SHA256 signatures for all webhook payloads.

Important

Store your webhook secret securely. If compromised, rotate it immediately by calling this endpoint again. You can rotate secrets once every 5 minutes.

Note

You must create your webhook secret before performing the action that triggers the notification. Otherwise, the notification won't include a signature and you won't be able to verify it.

Endpoint: Create Webhook Secret

export ORGANIZATION_ID="<YOUR_ORGANIZATION_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"

curl -X POST \
  https://app.bitgo-test.com/api/v2/webhook/secret \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "organizationId": "'"$ORGANIZATION_ID"'"
  }'
Step Result
{
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

Save this secret securely—you'll need it to verify incoming webhook notifications using the x-signature-sha256 header.

3. (Optional) Verify Webhook Notification

When BitGo sends a webhook notification, it includes an x-signature-sha256 header containing an HMAC-SHA256 signature. You can verify the notification is legitimate by passing the signature from this header along with the payload you received.

Endpoint: Verify Webhook Notification

export WEBHOOK_ID="<YOUR_WEBHOOK_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export SIGNATURE="<X_SIGNATURE_SHA256_HEADER_VALUE>" # Value from the x-signature-sha256 header in the webhook notification
export PAYLOAD="<YOUR_PAYLOAD>" # JSON payload as a string from the webhook notification body

curl -X POST "https://app.bitgo-test.com/api/v2/webhook/$WEBHOOK_ID/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "signature": "'"$SIGNATURE"'",
    "notificationPayload": "'"$PAYLOAD"'"
  }'
Step Result
{
  "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511",
  "isValid": true
}

4. (Optional) Simulate Organization Webhook

You can simulate your webhook with real data from the prior step or with placeholder data.

Endpoint: Simulate Organization Webhook

export ORGANIZATION_ID="<YOUR_ORGANIZATION_ID>"
export WEBHOOK_ID="<YOUR_WEBHOOK_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export ACCESS_TOKEN_ID="<YOUR_ACCESS_TOKEN_ID>"

curl -X POST "https://app.bitgo-test.com/api/v2/organization/$ORGANIZATION_ID/webhook/$WEBHOOK_ID/simulate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -d '{
  "bankAccountId": "string"
}'
Step Result
{
  "webhookNotifications": [
    {
      "id": "59cd72485007a239fb00282ed480da1f",
      "accessToken": "txRequest",
      "url": "https://webhook.site/f74addc1-c40a-4fce-879a-2d92b8d491c5",
      "hash": "db924f4cf2347ac5a6b464d3e8dc4a20cffc117eb29f4460645fbc34de171bfb",
      "simulation": true,
      "retries": 0,
      "webhook": "68531e154d28af627819bd3e183a930e",
      "updatedAt": "2025-06-19T20:48:43.525Z",
      "version": 1,
      "allowBlockedHosts": true,
      "payload": "string",
      "response": {
        "code": 0,
        "type": "string",
        "body": "string",
        "error": "string"
      }
    }
  ]
}

See Also