Webhooks are great if you’re running an app that needs current, instantaneous information from a third-party application. They’re simple to set up and very easy to use.

Graceful retries

Once a webhook notification is received, you should acknowledge success by providing an HTTP 20X response within 10 seconds. If a response isn't delivered within this time, we will attempt to resend the notification three more times according to the following schedule:

  • 30 seconds or more after the initial attempt
  • 2 minutes or more after the second attempt
  • 15 minutes or more after the third attempt

With each attempt, you'll also be given an X-Katana-Retry-Num HTTP header indicating the attempt number (1, 2, or 3).

Using temporary endpoint URLs, you can quickly inspect webhook requests. You can create these URLs using a free hosted service such as https://webhook.site.


You can configure the following events to trigger a message to registered webhooks:




sales order


Occurs when a new sales order is created.

sales order


Occurs when a sales order is updated (any attribute).

sales order


Occurs when a sales order is deleted.

sales order


Occurs when a new sales status is marked as PACKED.

sales order


Occurs when a new sales status is marked as DELIVERED.

sales order


Occurs when availability or expected date is updated for products or ingredients.


Since some events solve specific use cases(i.e. sales_order.packed and sales_order.delivered), if you're subscribed to both sales order updates and sales order status change to delivered, you may receive two identical webhook payloads since sales order status change to delivered is also considered an update.

Event object




Indicates the resource affected by this event.


Indicates registered webhook id that was used to send the payload.


The event that triggered this webhook, e.g. sales_order.delivered.


The object affected by this event. This will contain an id, status and an href to retrieve that resource. (href property doesn't apply to sales_order.deleted action)

Example event payload
HTTP/1.1 201 Created
Content-Type: application/json

  "resource_type": "sales_order",
  "action": "sales_order.delivered",
  "webhook_id": "<WEBHOOK_ID>",
  "object": {
  "id": "<SALES_ORDER_ID>",
  "status": "DELIVERED",
  "href": "https://api.katanamrp.com/v1/sales_orders/<SALES_ORDER_ID>"

Verifying webhook signatures

To prevent attackers from imitating valid webhook events, you should verify request signatures on your server.

Each webhook you register will return a single secret token in the token field of the API response body used to generate an HMAC using SHA-256. You only need to register a webhook once.

With each webhook request, you'll be given an x-sha2-signature HTTP header indicating the calculated signature.

Our Developer Hub provides a detailed guide for manually verifying webhook signatures.