Purpose
This guide explains how existing clients should update their webhook integration for the API v3 dedicated webhook structure.
For general webhook behavior, acknowledgment requirements, retry behavior, and endpoint registration, refer to the Skulytics Webhook Overview.
What Is Changing?
Previous webhook versions used broader event categories that could represent multiple types of product data changes.
API v3 introduces dedicated webhook events aligned with individual Public API data categories.
For example:
| Previous approach | API v3 approach |
|---|---|
| A general product update could represent multiple data changes. | Each data category has a dedicated event type. |
| Clients may need to inspect a large payload to identify what changed. | The type field identifies the affected data category. |
| One handler may process all product updates. | Events can be routed to specific internal services or workflows. |
What Remains Unchanged?
The following webhook behavior remains unchanged:
- The registered webhook endpoint URL.
- The use of HTTP POST requests.
- The use of JSON request bodies.
- The requirement to return HTTP 200 OK within 10 seconds.
- The existing retry schedule.
- The ability to receive all events through one endpoint.
Existing clients do not need to register a new URL solely to support API v3 webhook events.
Required Client Changes
Clients should update their webhook handler to:
- Recognize the new API v3 event types.
- Route events using the type field.
- Process the payload structure defined for each event.
- Avoid assuming that every event contains the complete product object.
- Safely handle event types that are not yet supported by their integration.
- Continue returning HTTP 200 OK within 10 seconds.
- Process repeated deliveries idempotently.
Event-Specific Payloads
Each webhook event contains data relevant to its corresponding API category.
For example:
- product_created contains the product data required to add a new product.
- product_updated contains the latest general product information.
- product_deleted contains the identity information required to remove the product.
- product_spec_updated will contain product specification data.
- product_inventory_quantity_updated will contain inventory quantity and availability data.
Clients should review the documentation for each webhook event before implementing its handler
Migration Checklist
Before enabling API v3 webhooks in production, confirm that:
- The existing webhook endpoint remains active.
- The endpoint can recognize API v3 event types.
- Events are routed using the type field.
- Each event-specific payload is processed correctly.
- Unsupported event types do not cause the endpoint to fail.
- HTTP 200 OK is returned within 10 seconds.
- Heavy processing occurs after acknowledgment.
- Duplicate deliveries can be processed safely.
- Product creation, update, and deletion events have been tested.
Summary
API v3 replaces broad webhook categories with dedicated events for individual product data categories.
Existing clients can keep the same registered endpoint and delivery configuration. The main migration requirement is to update the webhook handler so that it recognizes the new event types and processes each event-specific payload correctly.