Migration guide: Webhook deprecation

Deprecation timeline

❗️

Final shutdown date: November 30th

On November 30th, 2026, the legacy webhook service will be fully decommissioned. To avoid service interruptions, all integrations must be migrated to the new webhook service before this date.

Why migrate?

The new webhook service is a significant upgrade designed for modern integration needs. Key benefits include:

• Improved reliability: Enhanced delivery logic with consistent retry mechanisms.
• Granular control: Improved event management that can be easily configured to your specific use case.
• Enhanced supportability: The new service features improves logging and diagnostic tools. This allows Penneo to provide faster, more accurate assistance if you encounter issues with your event deliveries.
• Testing capabilities: The new service allows our you to test your endpoint setup before using your own domain.

For a deep dive into the new technical specifications, please refer to our Webhooks documentation.

API reference

You can identify the differences in our API Reference. In the documentation:

• Endpoints marked deprecated represent the legacy (v1) webhook service.
• Endpoints marked active represent the new (v2) webhook service.

Key Changes at a Glance

Migration steps

Follow these steps to ensure a seamless transition before the November 30th deadline:

1. Identify subscriptions on the old webhook service

Audit your current integration to identify which subscriptions are currently running on the legacy service. You can list all existing subscriptions via {Penneo_base_url}/api/v1/webhook/subscriptions endpoint or look for any calls to the {Penneo_base_url}/api/v1/webhook endpoints inside your integration.

2. Configure a v2 webhook subscription test

Before moving production traffic, set up a test to verify your listener's compatibility with the new service.

• The test event: The new service supports a specific eventType: webhook.subscription.test.
• How to trigger the test event: Create a subscription with the test eventType, then trigger a payload by calling: POST {Penneo_base_url}/webhook/api/v1/subscriptions/test
• Note: We suggest using a tool like Webhook.site during this phase to inspect the incoming JSON structure and headers.

3. Review security and reliability

The new service introduces enhanced features that may require logic changes on your end:

• Webhook integrity (optional): Review our documentation on how to verify the x-event-signature to ensure the request is authentically from Penneo.
• Retry Logic: Understand the new retry schedules and delivery guarantees to ensure your system handles potential duplicates gracefully.

4. Create subscription on new webhook service

Once testing is successful, point your production integration to the new endpoint structure: {Penneo_base_url}/webhook/api/v1. Map your legacy events to the new Supported eventTypes.

5. Decommission by deleting old webhook

After verifying that the new subscriptions are flowing correctly, delete your old v1 subscriptions. This prevents your system from receiving duplicate notifications for the same event during the transition period.

You can remove your legacy subscriptions using the following call: DELETE {Penneo_base_url}/api/v1/webhook/subscriptions/{subscriptionId}

What happens after November 30th?

If you haven't migrated to the new webhook subscription service, you will no longer receive event updates after November 30th.

Need help? If you have questions regarding your specific integration or need to schedule a technical review, please contact your Account Manager or reach out to our support team.