Ctrl+K

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

Suspensions

BitGo suspends sending notifications when either of the following occur for a webhook:

  • At least 100 notification failures within 1 week.
  • At least 500 notification failures over the lifetime.

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