# Create Enterprise Webhooks

Source: https://developers.bitgo.com/docs/webhooks-enterprise

## 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 confirms on chain immediately after sending, or if it's a <a href="https://bitcoinops.org/en/topics/replace-by-fee/" target="_blank" rel="noreferrer">Replace-by-fee (RBF)</a> transaction.

### Enterprise Webhook Types

BitGo offers the following types of webhooks for wallets:

| Type | Triggers When |
| :--- | :------------ |
| `accessToken` | BitGo creates an access token. |
| `bankAccount` | A user adds a bank account. |

## Prerequisites

* [Get Started](/docs/get-started-intro)
* If you want to verify webhook notifications, ensure your enterprise has a webhook secret (see [Create Webhook Secret](/reference/v2webhooksecretcreate)).

## Cookbook

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

<Cookbook slug="create-enterprise-webhooks" title="Create Enterprise Webhooks" />

## 1. Create Enterprise Webhooks

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

>Endpoint: [Create Enterprise Webhook](/reference/v2enterprisewebhookadd)

```shell cURL
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 JSON
{
  "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": [],
  "identityStatus": []
}

```

## 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](/reference/v2webhooksecretcreate) endpoint).

>Endpoint: [Verify Webhook Notification](/reference/v2webhooknotificationverify)

```shell cURL
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 JSON
{
  "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](/reference/v2enterprisewebhooksimulate)

```shell cURL
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 JSON
{
  "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

* [API Reference: Create Enterprise Webhook](/reference/v2enterprisewebhookadd)
* [API Reference: Create Webhook Secret](/reference/v2webhooksecretcreate)
* [API Reference: Simulate Enterprise Webhook](/reference/v2enterprisewebhooksimulate)
* [API Reference: Verify Webhook Notification](/reference/v2webhooknotificationverify)
* <a href="https://webhook.site/" target="_blank" rel="noreferrer">Webhook.site</a>