Webhooks

Webhooks Overview

Overview

You can set up webhooks to programmatically receive callbacks or notifications from BitGo when specific events occur. For example, you can create webhooks to receive deposit notifications or on-chain confirmations for withdrawals.

To ensure streamlined operations, it's important that you configure your application to succeed even if:

  • You encounter transient network errors.
  • You receive the same webhook twice, due to improper acknowledgement.

For testing purposes, you can receive webhooks and control response codes using third-party services such as Webhook.site.

Security

You verify the authenticity of webhook notifications from BitGo using a secret token and signatures in the headers:

  • Key - BitGo generates a unique secret token that you can initiate or rotate through using the Create webhook secret endpoint. Your secret token is your key to signing webhook payloads.
  • Sign - Webhook notifications utilize your key in conjunction with an HMAC hashing algorithm (x-signature-sha256) to create a cryptographic hash. This hash is the unique signature for the webhook.
  • Verify - You can call the Verify Webhook Notification endpoint to verify webhook notifications that you receive.

Idempotency

BitGo supports idempotency by enabling you to include a unique key, referred to as an idempotency-key, in the request header. This helps you avoid processing duplicate webhook notifications.

Retries

BitGo servers make POST HTTP requests to the URL defined in a JSON payload. If we don't receive a successful HTTP 200 OK response, we attempt to retry the webhook with an increasing delay between each retry. After the original attempt, BitGo will make up to 7 additional attempts. Retry intervals are as follows:

1, 5, 10, 30, 60, 120, 240 minutes

Egress IP Addresses

BitGo sends webhook notifications from a set of known IP addresses. If your infrastructure uses a whitelist to restrict inbound traffic, you can download the list of BitGo egress IPs for both testnet and production environments.

Suspensions

BitGo suspends a webhook after 500 consecutive failed deliveries, or after more than 100 consecutive failures within a 7-day period. A successful delivery (HTTP 2xx) resets the failure count.

BitGo also auto-blocks a destination URL after 10 non-retryable 4xx responses within 1 hour. While a URL is blocked, BitGo stops delivering to every webhook registered to that URL. A successful delivery doesn't reset the counter.

If BitGo suspends a webhook, you must delete the suspended webhook and create a new one.

Guides

BitGo currently supports the following webhooks:

See Also