Crypto-as-a-Service: Create Enterprise Webhooks

Set up enterprise-level webhooks to receive notifications for events specific to individual end-user enterprises in your CaaS platform. See the Guide.

  1. Create a webhook that notifies you whenever a specific enterprise creates an access token. Enterprise webhooks receive notifications for events specific to individual end-users.

    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 it works correctly before going live.

    API Reference

// 1. Create Enterprise Webhooks
export ENTERPRISE_ID="<YOUR_ENTERPRISE_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/enterprise/$ENTERPRISE_ID/webhooks \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "type": "accessToken",
    "url": "'"$URL"'",
    "label": "'"$LABEL"'"
  }'

// 2. Create Webhook Secret (Optional)
export ENTERPRISE_ID="<YOUR_ENTERPRISE_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 '{
    "enterpriseId": "'"$ENTERPRISE_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 Enterprise Webhook (Optional)
export ENTERPRISE_ID="<YOUR_ENTERPRISE_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/enterprise/$ENTERPRISE_ID/webhook/$WEBHOOK_ID/simulate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
  -d '{
  "accessTokenId": "'"$ACCESS_TOKEN_ID"'"
}'
Response 
// 1. Create Enterprise Webhooks Response
{
  "id": "6854341f9b1bb1a97f4ad2d8af07f178",
  "label": "my-enterprise-access-token-webhook",
  "created": "2025-06-19T16:00:31.738Z",
  "scope": "enterprise",
  "enterpriseId": "62c5ae8174ac860007aff138a2d74df7",
  "type": "accessToken",
  "url": "https://webhook.site/f74addc1-c40a-4fce-879a-2d92b8d491c5",
  "version": 2,
  "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 Enterprise 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": 2,
      "allowBlockedHosts": true,
      "payload": "string",
      "response": {
        "code": 0,
        "type": "string",
        "body": "string",
        "error": "string"
      }
    }
  ]
}