Skip to main content

none

Support

Use Webhooks

Updated

Webhooks are a useful way to inform a third party service of an action performed on a LocknCharge device. Webhooks can be configured to fire on one or more of the following events:

  • Bay Reserved
  • Bay Accessed
  • Bay Closed
  • Bay Stuck
  • Bay Breach
  • Bay Temporarily Locked

Webhooks can be configured in the LocknCharge FUYL Portal via the Integrations menu.

Configure Webhooks

  1. Go to the 'Webhooks' tab and click the 'New Webhook' button, or edit an existing webhook if applicable.
  2. Enter the details outlined below:
    Name: A name by which the webhook will be referred to.
    URL: The endpoint to which the webhook will make a HTTP/HTTPS POST request to.
    Description: An optional description.
    Auth Bearer Token: An optional security token required by the endpoint.
    Event Types: The event that this webhook will be triggered from, at least one event type must be selected here. See here for more details on the event types.
  3. To verify the configuration details, click 'Test' at the bottom of the form.
  4. Click 'Save' which will create the webhook and redirect you back to the Webhook list screen.

Saved webhooks can be disabled via the 'Active' toggle switch on the configuration screen. This allows a webhook to be turned on/off while maintaining the configuration details.

Testing Webhooks

On the webhook configuration form, click 'Test' which will send a sample payload to the specified webhook URL. This can be used to debug/verify the webhook configuration details. See below for an example.

Timeout

The webhook request will time out after 5 seconds. If the request takes longer than 5 seconds, the request will be aborted. The webhook request should be acknowledged with minimal processing time as soon as it is received to avoid timing out.

Automatic Retries

Webhook requests may fail due to timeout issues or other errors. In the event of a failed webhook request, the system retries immediately. Subsequently, it will retry up to 7 times over exponentially increased intervals (15s, 1m, 5m, 30m, 1hr, 3hrs, 6hrs).

After the 7th failed retry (6hrs), the request will be aborted.

Sample Webhook Payload

{
  data: {
    bayName: 'Webhook Test Bay',
    bayId: 'S-WebhookTestStation_B-1',
    bay: 1,
    bayTags: ['iPad'],
    stationId: 'S-WebhookTestStation',
    stationName: 'Webhook Test Station'
  },
  origin: 'S-WebhookTestStation',
  timestamp: '2023-02-03T06:08:40.855Z',
  type: 'BAY_BREACH',
  userType: 'SYSTEM'
}

Payload Structure

Data (data: {})

Contains locker and bay details:

  • bayName: Bay name, or ID if name not specified.
  • bayId: Bay ID (Mirrored in the FUYL Portal)
  • Bay: Bay Number
  • bayTags: List of tags associated with this bay.
  • stationId: ID of locker (Mirrored in the FUYL Portal)
  • stationName: Locker name, or ID if name not specified.
  • user: Information about the user that triggered the event (See user structure below)

Event Type (type: )

One of six supported event types:

  • BAY_CREDS_CACHED: Bay reserved
  • BAY_CREDS_CLEARED: Bay accessed
  • BAY_CLOSED: Bay closed
  • BAY_STUCK: Bay stuck (unable to open after 5 retries)
  • BAY_BREACH: Bay breached (opened without instruction)
  • BAY_TMPBAN: Bay temporarily locked due to multiple failed access attempts.

User Type (userType:)

One of four defined user types:

  • ADMIN: Event was triggered by a FUYL Portal admin.
  • APP_CLIENT: Event was triggered by an integrated external system.
  • USER: Event was triggered by an internal or external user.
  • SYSTEM: Event was triggered by the system i.e. BAY_CLOSED.

User (user: {})

  • id: User ID
  • name: User name
  • email: User email (FUYL Portal admins only)
  • externalRefId: Custom reference id (Internal users only)
  • tags: A list of custom labels about the user (Internal users only)

Related articles