Skip to main content

Create a new webhook endpoint

POST 
/api/v1/sdk/stores/:storeId/webhooks

This endpoint creates a new webhook subscription for your store. Webhooks allow you to receive real-time notifications when events occur.

Authentication: Requires Private API Key (sk_*) with Administer permission

Available Event Types:

Cart Events: cart.created, cart.item_added, cart.item_updated, cart.item_removed, cart.abandoned, cart.recovered, cart.cleared, cart.checkout_started

Order Events: order.created, order.status_updated, order.confirmed, order.shipped, order.delivered, order.cancelled, order.refunded, order.partially_shipped, order.partially_delivered

Customer Events: customer.created, customer.updated, customer.deleted

Product Events: product.created, product.updated, product.deleted, product.inventory_updated, product.variant_created, product.variant_updated, product.variant_deleted

System Events: webhook.test, webhook.endpoint_created, webhook.endpoint_updated, webhook.endpoint_deleted

Currently Active Events: Cart events (created, item_added, item_updated, item_removed, cleared) and Order events (created, status_updated, shipped, delivered) are currently being sent by the system.

Webhook Payload:

  • JSON POST request to your URL
    • Headers include: X-Webhook-Event (event type), X-Sonar-Webhook-HMAC-SHA256 (signature), Content-Type: application/json
    • Body contains event data specific to the event type

Use Cases:

  • Real-time order fulfillment automation
    • Inventory synchronization
    • Customer communication triggers
    • Analytics and reporting
    • Third-party integrations

Important Notes:

  • URL must be HTTPS (HTTP not supported in production)
    • Your endpoint must respond with 2xx status within 5 seconds
    • Failed deliveries are retried up to 3 times with exponential backoff
    • Store the returned secret securely for signature verification
    • Maximum 10 webhook endpoints per store

Error Scenarios:

  • 400 BAD REQUEST - Invalid URL, invalid events, or validation errors (Error code: INVALID_REQUEST)
    • 409 CONFLICT - Too many webhooks or duplicate URL (Error code: TOO_MANY_WEBHOOKS or DUPLICATE_URL)
    • 401 UNAUTHORIZED - Invalid or missing API key (Error code: INVALID_API_KEY)
    • 403 FORBIDDEN - Insufficient permissions (Error code: INSUFFICIENT_PERMISSIONS)

Request​

Responses​

Webhook endpoint created successfully with secret