V1 webhooks are being deprecated

Circle is retiring Version 1 (V1) webhooks. Version 2 (V2) is the supported long-term model, and all webhook functionality is moving to it.

 

What this means for you:

• New webhooks: use V2. Every new webhook subscription should be created on V2. V1 is no longer recommended for new integrations, and the ability to create new V1 subscriptions will be turned off ahead of full retirement. All Circle Products are now supported on V2. 
• Existing V1 webhooks: plan to move them to V2. Your current V1 subscriptions keep delivering events for now, but they will stop working when V1 is retired. Each one needs to be recreated on V2 and your endpoint updated to handle the V2 format.

If you only ever created your webhooks recently and they are already on V2, no action is required. 

What is a webhook?

A webhook is a way for Circle to notify your application when an event occurs. Instead of repeatedly calling a Circle API to check for updates, your application registers an HTTPS endpoint. Circle sends an event notification to that endpoint when a supported event occurs, such as a change in transaction status.

 

Your application should authenticate or verify incoming notifications, process events idempotently so that duplicate deliveries do not cause duplicate actions, and return a successful HTTP response after accepting an event.

Why are there two webhook versions?

Circle has two generations of webhook technology:

• Version 1 (V1) is the legacy webhook model used by existing Circle Mint customers. It is supported for existing subscriptions only.
• Version 2 (V2) is the current webhook model. It is the recommended model for all new webhook subscriptions, and it covers Circle Mint events as well as events from Circle's other supported products.

 

The two versions use different delivery, event, payload, and signature-verification models. Because of these differences, a V1 subscription is not automatically converted to V2. Existing V1 subscriptions continue to deliver events during the supported migration period, and moving to V2 is a separate technical upgrade that you control.

V1 and V2 capabilities

 

What changes when you upgrade

Moving an integration from V1 to V2 is a technical change, not a setting. V2 uses a different event structure, a different event naming model, and a different signature-verification method. Your integration may need updates to:

• Parse the V2 notification structure.
• Handle the V2 event types used by your Circle products.
• Verify V2 signatures.
• Deduplicate events while V1 and V2 subscriptions are running in parallel.

Review the V2 developer documentation for the products and event types you use before you change production traffic.

Recommended migration approach

To reduce the risk of missed or duplicate events:

 

1. Inventory your active V1 subscriptions, endpoints, and event-handling logic.
2. Build a separate endpoint that supports the V2 payload structure, event types, and signature-verification requirements. Leave your existing V1 endpoint unchanged.
3. Create the corresponding V2 subscription and point it at the new endpoint.
4. Keep your V1 subscription active and run V1 and V2 in parallel while you validate V2 delivery and processing.
5. Once you have confirmed V2 is working as expected, delete the V1 subscription before the communicated V1 retirement deadline.

 

Circle will provide advance notice before disabling the creation of new V1 subscriptions or retiring existing V1 delivery.