Webhooks
Customize how Storeganise works and integrate with external software.
Contents
- Overview
- How to set up a webhook
- How to set up the webhook receiver
- Response status
- How to secure your webhook
Overview
Webhooks are used to receive notifications when events happen within the Storeganise system.
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.
- Customize how valet orders or self-storage move-ins work.
- Integrate CRMs or other software
- Integrate with Zapier, etc.
How to set up a webhook
In the Storeganise operations portal, go to Main Settings > Developer > Webhooks. Note that only managers can access these settings.
Click the + button to create a new webhook.
Enter a Webhook URL
This should be an HTTPS endpoint that is configured to receive a POST request with a JSON body payload in the format below. The data
the property will vary depending on the event notification type.
Select which events to subscribe to
For example, if a valet order is created, webhooks that subscribe to the job.valetOrder.created
the event will receive the valet order jobId
when a valet order is created within the Storeganise system.
And if a self-storage move-in is scheduled, webhooks that subscribe to the job.unit_moveIn.created
the event will receive the jobId
of that move-in.
Add Alert Receivers
You can decide who to notify when a webhook fails by adding their email address to the "Alert Receivers" field. There must be at least one email address (see screenshot for example).
Update Webhook
Click on the newly created webhook to see the details and make changes.
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 with a 200 HTTP status code when completed.
- Respond within 2 seconds.
Example request (what your endpoint would receive)
POST https://api.yourapp.com/webhook-handler Content-Type: application/json;charset=UTF-8 { "id": "5bf48bd975970f170a8e42b7", "created": "2021-11-21T11:26:32.105Z", "type": "job.unit_moveIn.created", "data": { "jobId": "5bf540e8d986a91cd713affe" } }
Example response (what your endpoint would send back)
200 OK
How to work with the webhook data
Within your webhook handler/function you can use the data.jobId
from the example above to fetch the information related to that job. This would be done by calling the Storeganise API using an API key. You can then use the information stored in that job to do things such as:
- create a notification in Slack that a moveIn has been scheduled
- add custom charges to the associated UnitRental
- send an SMS to the customer
Response status
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.
How to secure your webhook
The request comes with a sg-signature
header, use it with the webhook secret setting to verify the sender authenticity of this webhook call. You can do so by comparing it with
crypto.createHmac('sha256', webhook_secret).update(req_body).digest('base64')
If they are equal, the request is secure
Webhook secret can be seen from the /api/v1/admin/settings
request, inspecting the response like below: