Create Enterprise Webhooks

Overview

You can create wallet webhooks to receive an HTTP callback from BitGo to a specified URL when specific wallet events occur. Wallets can have up to 10 webhooks of each enterprise-webhook type.

Note: An unconfirmed webhook notification doesn't trigger if a transaction is confirmed on chain immediately after it's sent, or if it's a Replace-by-fee (RBF) transaction.

Enterprise Webhook Types

BitGo offers the following types of webhooks for wallets:

TypeTriggers When
accessTokenAn access token is made.
bankAccountA bank account is added.

Prerequisites

1. Create Enterprise Webhooks

The following example creates a webhook that notifies you whenever an access token is created.

Endpoint: Create Enterprise Webhook

  • cURL
1 2 3 4 5 6 7 8 9 10 11 12 13 14 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"'" }'
Step Result
  • JSON
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "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

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).

Endpoint: Verify Webhook Notification

  • cURL
1 2 3 4 5 6 7 8 9 10 11 12 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"'" }'
Step Result
  • JSON
1 2 3 4 { "webhookId": "wh119ecd15a4adf811f8f552fde21b9d819b4dc9a7f04c51513395816703c73511", "isValid": true }

3. (Optional) Simulate Enterprise Webhook

You can simulate your webhook with real data from the prior step or with placeholder data (also known as dummy data).

Endpoint: Simulate Enterprise Webhook

  • cURL
1 2 3 4 5 6 7 8 9 10 11 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"'" }'
Step Result
  • JSON
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "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" } } ] }

See Also