Legacy Webhook to V3 Migration

Overview

We are excited to introduce Webhook V3, upgrade to our webhook system that delivers enhanced functionality, security, and usability. Webhook V3 includes a comprehensive dashboard for managing all webhook-related actions through an intuitive interface and enhanced troubleshooting tools such as detailed delivery logs and update history tracking, making monitoring and maintaining your integrations easier.

As we phase out Legacy Webhook, all users will be transitioned to Webhook V3 to ensure continued support and access to these new capabilities. This guide outlines the key differences between the two versions. It provides step-by-step instructions for updating your API integration, ensuring a smooth transition, and helping you make the most of the upgraded system

note

Field Nation will handle the migration, and no additional steps need to be taken from outside users during the migration.

warning

Legacy Webhook API will continue to function even after migrating to V3, but it will eventually be deprecated. Read the API Migration Process below to switch to the Webhook V3 API.

New Features in Webhook V3

• Dashboard Access: Available for managing and monitoring your webhooks.
• API Parity with UI: The API now provides the same capabilities as the dashboard, enabling full automation and integration.
• Backward Compatibility: The delivery payload format remains unchanged, ensuring compatibility with existing systems.
• Delivery Logs and History: Access new endpoints to view detailed delivery logs and webhook update history, making tracking and troubleshooting events easier.
• Change Inspection: The Update History feature allows you to inspect all changes made to your webhooks over time.
• Two-Week Log Retention: Delivery logs are stored and accessible for up to two weeks, providing a reliable record of webhook events.
• Manual Retry Option: Easily retry a previous webhook delivery directly from the dashboard or API, ensuring important messages are not missed.
• Enhanced Security: Improved security features, including updated payload validation and IP whitelisting, help secure your webhook operations. Read Securing Webhooks for details.
• Advanced Retry Mechanism: The new retry strategy includes an exponential backoff with a 10-minute recovery window, ensuring no messages are lost if the receiver recovers within this time. Webhook delivery can be retried up to seven times. Read Retry Strategy for details.

Feature Differences

Feature	Legacy Webhook	Webhook V3
Notification Emails	Categorized by type (too_many_waiting, max_retry, too_many_fails).	Single input for multiple emails; all notifications sent to all provided addresses.
Secret Handling	Secrets were exposed via API.	Secrets are masked in the API for added security.
Secret Requirement	Secrets were optional.	Secrets are always available (either user-provided or auto-generated UUID). Ignoring is not recommended.
Event Batching	Similar events were batched within a short time window.	No batching; events are sent immediately, close to the original event time.
Authentication	Used a custom token specific to the legacy webhook.	Uses a common access token from our Client API.
Retry Logic	Option to disable retries on failure.	Automatic 7 retries before considering the message as failed. Read Retry Logic Details for details.
Security Header	Fn-hash header (to be deprecated).	New X-Fn-Signature header using HMAC-SHA256 for secure payload verification. Read Validate Incoming Requests for details.

Webhook V3 API Migration Process

Step 1: Ensure you have the correct API access

Webhook V3 uses the access token from Client API and uses api.fieldnation.com, unifying the API access and base URL for our API products. Read Webhook API Reference for details.

Step 2: Update API base URL

Replace micro.fndev.net or micro.fieldnation.com with our Client API Base URL. Webhook V3 base URLs are api-sandbox.fndev.net and api.fieldnation.com.

Step 3: Adjust to the Request/Response Structure

There are a few differences between Legacy Webhook data and Webhook V3 data.

Major changes between Legacy Webhook and Webhook V3 are:

Field	Legacy Webhook	Webhook V3	Notes
Webhook ID	_id	webhookId	Identifier for the webhook
Status	active	status	Represents webhook status
Retries	no_retries	Deprecated	Retries feature removed
Notification Email	notification	notificationEmail	Field for notification email

Here is an example response after creating a webhook:

Webhook V3

{
    "metadata": {
        "timestamp": "Wed, 04 Sep 2024 14:37:54 GMT"
    },
    "result": {
        "id": 23
        "webhookId": "9582b275-e841-4f47-9a31-553d1d771d13",
        "companyId": 1,
        "userId": 1,
        "url": "https://testwebhook.com",
        "method": "post",
        "status": "inactive",
        "secret": "7a40c854-fb89-4064-aa11-55be48d8a21e",
        "events": [
            "workorder.created",
            "workorder.status.approved"
        ],
        "notificationEmail": "user1@test.com,user2@test.com",
        "createdAt": "2024-09-04T14:37:54.000Z",
        "updatedAt": "2024-09-04T14:37:54.000Z",
    }
}

Legacy Webhook

{
    "_id": "66d870c44d529b00114bdedf",
    "company_id": 1,
    "user_id": 1,
    "url": "https://testwebhook.com",
    "method": "POST",
    "active": false,
    "secret": "123123",
    "events": [
        "workorder.created",
        "workorder.status.approved"
    ],
    "no_retries": false,
    "notification": {
        "too_many_waiting": {
            "email_addresses": [
                "user1@test.com",
                "user2@test.com"
            ]
        },
        "max_retry": {
            "email_addresses": [
                "user1@test.com",
                "user2@test.com"
            ]
        },
        "too_many_fails": {
            "email_addresses": [
                "user1@test.com",
                "user2@test.com"
            ]
        }
    },
    "metadata": {
        "message": "Please migrate over to new webhook and start using the latest api."
    }
}

Step 4: Test Your Integration

• Sandbox Testing: Use the provided sandbox environment to test your updated API integration.
• Verify Payloads: Read our API documentation and follow the provided OpenAPI Spec. Make sure the webhook CRUD operation provides an updated request payload and handles the updated response.

Step 5: Deploy the Changes

Once testing is complete and you are confident in your updates, deploy the changes to your production environment. Monitor for any issues and ensure that everything is functioning as expected.

Forward Compatibility and Future Deprecation

Your existing Legacy Webhooks API integration will continue to work after migrating to Webhook V3, as the system has been designed to be forward-compatible. However, it is crucial to update your API integration as the old API will be deprecated in the near future. Once deprecated, any legacy API calls will cease to function, potentially disrupting your services.

Conclusion

We strongly encourage you to complete this migration as soon as possible to ensure uninterrupted service and take advantage of Webhook V3's enhanced security and flexibility. If you encounter any issues during the migration, contact support for assistance.