Create Enterprise Webhooks

Create enterprise webhooks to receive HTTP callbacks when enterprise-level events occur. See the Guide.

  1. Create an enterprise webhook that notifies you whenever an enterprise-level event occurs. The example creates an accessToken type webhook that triggers whenever BitGo creates an access token. Wallets can have up to 10 webhooks of each enterprise-webhook type.

    Prerequisites:

    API Reference

  2. You can verify the webhook notification is legitimate by passing the payload you received in the prior step as a JSON string with your webhook secret (created with the Create webhook secret endpoint).

    API Reference

  3. You can simulate your enterprise webhook with real data from the prior step or with placeholder data. Pass an access token ID to trigger the simulation.

    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. (Optional) Verify Webhook Notification
export WEBHOOK_ID="<YOUR_WEBHOOK_ID>"
export ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export SIGNATURE="<YOUR_WEBHOOK_SECRET>" # Created using the Create webhook secret endpoint
export PAYLOAD="<YOUR_PAYLOAD>" # JSON payload as a string that you received in the prior step

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"'"
  }'

// 3. (Optional) Simulate Enterprise Webhook
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. (Optional) Verify Webhook Notification Response
{
  "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511",
  "isValid": true
}

// 3. (Optional) Simulate Enterprise Webhook 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"
      }
    }
  ]
}