Crypto-as-a-Service: Create Organization Webhooks

Set up organization-level webhooks for CaaS providers to receive notifications for events across your entire organization. See the Guide.

  1. Create a webhook that notifies you whenever someone adds a bank account to your organization. Organization webhooks receive notifications for events that apply to your entire CaaS organization.

    API Reference

  2. Create a webhook secret to verify webhook notifications. BitGo uses this secret to generate HMAC-SHA256 signatures for all webhook payloads. Store your secret securely and create it before triggering notifications.

    API Reference

  3. Verify that webhook notifications genuinely originate from BitGo by validating the HMAC-SHA256 signature in the x-signature-sha256 header against the received payload.

    API Reference

  4. Test your webhook with real or placeholder data to ensure the configuration is correct before going live.

    API Reference

// 1. Create Organization Webhooks
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"'"
  }'

// 2. Create Webhook Secret (Optional)
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"'"
  }'

// 3. Verify Webhook Notification (Optional)
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"'"
  }'

// 4. Simulate Organization Webhook (Optional)
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"
}'
Response 
// 1. Create Organization Webhooks Response
{
  "success": "true",
  "data": {
    "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": []
}

// 2. Create Webhook Secret (Optional) Response
{
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0"
}

// 3. Verify Webhook Notification (Optional) Response
{
  "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511",
  "isValid": true
}

// 4. Simulate Organization Webhook (Optional) Response
{
  "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"
      }
    }
  ]
}