Webhooks

Customize how Storeganise works and integrate with external software.

Overview
How to set up a webhook
How to set up the webhook receiver
Response status
How to secure your webhook
Webook definitions

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:

Webhook definitions

business.updated : Global business settings has been updated
site.settings.updated : This event fires whenever the site settings (advanced settings) have been updated or modified.
site.availability.updated : The event fires when the site state has been changed or updated (i.e., available, not available, etc).
addon.installed : Triggered when a new addon is added/installed.
addon.customFields.validate : Addon custom fields have been updated
items.updated : The event fires upon an update to an item within a valet order.
job.unit_moveIn.create.started : Triggered on order initiation (customer side) but not completed or submitted yet.
job.unit_moveIn.started : Triggered upon order confirmation. After this, the invoice is generated, etc.
job.unit_moveIn.created : Triggered upon customer order submission, but needs to be approved/confirmed by the operators.
job.unit_moveIn.completed : Fires upon the successful completion of a move-in job order.
job.unit_moveIn.cancelled : Fires when the operator cancels a move-in job order.
job.unit_moveOut.created : Fires when an operator schedules a move-out from the unit.
job.unit_moveOut.completed : Fires when the move-out job order is completed, regardless of the unit state; either available or blocked.
job.unit_moveOut.cancelled : Fires on move-out order cancellation (operator initiated).
job.unit_transfer.completed : Fires upon unit transfer completion.
job.valetOrder.submitted : Fires upon a valet order submission (customer side).
job.valetOrder.created : Triggered on valet order submission, (needs to be approved/confirmed by operators).
job.valetOrder.started : Triggered upon valet order confirmation. After this, the invoice is generated, etc.
job.valetOrder.completed : Fire upon successful completion of the valet order.
job.valetOrder.cancelled : This event fires whenever a valet order has been canceled (initiated by the operator).
unit.reserved : Event fires when the customer initiates a unit reservation (waiting for approval/confirmation by the operator).
unit.occupied : This event occurs when a successful completion of the move-in or transfer process triggers a change in the unit state from available to occupied.
unit.blocked : Fires when a user manually blocks a unit from the management portal and provides a reason for doing so.
unit.unassigned : This event is triggered when an operator takes action to unassign a unit from a user.
unit.unblocked : Fires when an operator manually unblocks the unit
unit.archived : Event fires when an operator archives a unit within the management portal.
unitRental.markOverdue : Fires when a unit’s associated invoice becomes past due.
unitRental.unmarkOverdue : Fires upon invoice overdue status removal
unitRental.updated : Fires whenever any change is made to a unit’s rental details (i.e., price, state, details, etc.).
unitRental.invoice.created : The event fires upon the generation of an invoice associated with a unit rental.
user.created : Fires whenever a new user is created within the system
user.updated : Fires whenever a user’s information is modified within the system
user.billing.updated : The event fires upon modification of user billing details.
valet.invoice.created : The event fires upon the creation of an invoice linked to a valet order.