Contents

Overview

Webhooks are used to receive notifications when events happen within the Storeganise system. Currently this applies to when invoices are generated for a customer.

You can use Storeganise webhooks to do things such as:

  • Automatically add new invoices to your accounting software.

  • Take automated payments for new invoices using a third party or custom payment gateway.

How to set up a webhook

In the Storeganise operations portal, go to Main Settings > Developer > Webhooks.

Click the + button to create a new webhook.

Enter a Webhook URL

This should be a HTTPS endpoint that is configured to receive a POST request with a JSON body payload in the format below.  The data property will vary depending on the event notification type.

Select which events to subscribe to

For example, if an invoice created, webhooks that subscribe to the invoice.create event will receive the invoice data when invoices are created in the Storeganise system.

How to set up the webhook receiver

The webhook receiver is an HTTPS endpoint on your system, which will be called by Storeganise when events happen in the system. It has the following requirements:

  • Serve over HTTPS for security.

  • Accept a POST request. The payload is delivered in application/json  content type.

  • Respond a 200 HTTP status code when completed.

  • Respond within 2 seconds.

Example request (what your endpoint would receive)

POST https://api.yourapp.com/invoices
Content-Type: application/json;charset=UTF-8
{
  "id": "5bf48bd975970f170a8e42b7",
  "created": "2018-11-21T11:26:32.105Z",
  "type": "invoice.create",
  "data": {
    "invoice": {
      "id": "5bf540e8d986a91cd713affe",
      "state": "draft",
      "total": 90,
      ...
    }
  }
}

Example response (what your endpoint would send back)

200 OK

Notes

When a webhook notification is sent to your system, it expects the 200 HTTP response once it has succeeded.  If the request fails or it receives a non-200 HTTP response, the request will be retried 2 more times.  If it continues to fail the related job will be marked as failed.

Did this answer your question?