Migration Guide

The new Webhooks service provides a more robust, reliable, faster, and feature-rich integration experience. While the new system introduces many enhanced capabilities, it also deprecates some existing features to streamline functionality and improve performance.

This document will guide you through:

• Understanding new features and improvements
• Mapping changes between the old and new webhook payloads
• Best practices for implementing the new system

---

Key Benefits

Here’s a summary of the new service and improvements:

• Improved Performance: Reduced response times and increased resiliency.
• Events Catalog: Subscribe to specific events or event categories.
• Visibility: New UI for notifications and send attempts.
• Enhanced controls: UI and API management, including notifications, resend up to 30 days.
• No holdups: Removed existing 10s inherent delay used in V1 to best-effort order messages.

Changelog

1. Event Filtering/subscription
   1. You can now subscribe to events by their eventType , reducing the need to process unwanted events.
2. Event types
   1. A new syntax for event types is introduced. Mapping of V1 to V2 event types is provided in Event Mapping: Old to New.
3. Event ordering
   1. The 10-second delay previously applied to certain events has been removed.
   2. While we still make efforts to send notifications in order (per resource), Fireblocks doesn’t guarantee delivery of
      events in the order in which they’re generated. Your endpoint shouldn’t expect the delivery of events in
      order.
4. Resend Capability (Under Development)
   1. We now allow resending events for up to 30 days from the original event timestamp.
   2. To initiate a resend, use the resourceId field of the event's data object.
5. Improved Retry Logic
   1. Retry attempts for failed webhook deliveries now span a longer time window to ensure delivery success.
6. Error Rate Monitoring and Disabling
   1. Webhooks with an error rate exceeding a specific threshold will be automatically disabled to protect the system
      integrity.
   2. Handle events asynchronously with queues and quickly return a 2xx status code to prevent performance issues in your application

Notifications Object Differentiation

The new webhook payload format is designed for clarity and extensibility. Below is the structure of the new payload:

📘

Note:

Although the event payload remains unchanged, the notification object has been updated, requiring some adjustments on your end for parsing. Additionally, you’ll need to register your webhook listener on Push API V2 to start using it.

Key Changes from the Old Payload

• id : Unique identifier for the webhook notification object.
• type → eventType : Unified event naming for consistency.
• resourceId : Introduced to enable precise identification of the entity associated with the event.
• tenantId → workspaceId : The tenant/workspace identifier associated with the event.
• timestamp → createdAt : Describes when the webhook was created.

📘

Note:

Review Webhooks V2 documentation and implement accordingly. Please be sure to remove V1 webhooks under the Admin center.

Event Mapping: Old to New

To make the migration seamless, below is the mapping of old event names to new ones:

FAQs

Will it be easy to switch back to the original implementation if something goes wrong?

The implementation of the new webhooks is not a migration but a completely new service that runs alongside the original version (V1). You can maintain both integrations in parallel until you're confident in the new setup. This ensures a smooth transition without needing to revert.

How long can we keep both V1 and V2 running?

Both services will run in parallel until V1 is officially sunset by January 2026.

Are there changes to the payload or our business logic?

The payload and your business logic remain the same. However, the notification object has changed, and you will need to register your webhook server on Push API V2 to start using it.

Will new events be backward compatible with V1?

New events developed by Fireblocks will only be supported in V2 moving forward.

Where can I get help during the migration?

Our support team is available at Fireblocks Support to assist you with any questions or concerns.

What happens if I don’t migrate by the EOL date?

After the EOL date, the current Webhooks v1 will no longer be supported, and access will be disabled.