Webhooks

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.

Events

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

Resource

Event

Description

sales order

sales_order.created

Occurs when a new sales order is created.

sales order

sales_order.updated

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

sales order

sales_order.deleted

Occurs when a sales order is deleted.

sales order

sales_order.packed

Occurs when a new sales status is marked as PACKED.

sales order

sales_order.delivered

Occurs when a new sales status is marked as DELIVERED.

sales order

sales_order.availability_updated

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

Attribute

Description

resource_type

string
Indicates the resource affected by this event.

webhook_id

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

action

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

object

object
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.