Webhooks

Maple uses webhooks to notify you of activity occurring for your shifts. Rather than your application calling our API, webhooks allow Maple to call your API or server. Upon receiving these events from Maple, your application can react.

The specific actions your webhook endpoint takes differ based on the event. Some examples include:

• Creating shifts in your platform when they are made available in Maple
• Removing workers from shifts when they are unassigned in Maple

Creating a webhook endpoint

To create a webhook endpoint on your server, add a new route with the desired URL. For each event, Maple POSTs to your endpoint with a JSON request body.

To configure the endpoint:

1. From your Maple account, navigate to the Agency View.

2. From Settings, click Integration API and access the Webhooks tab.

   

3. From the Endpoints tab, select Add Endpoint.

4. Enter the Endpoint URL and, in Message Filtering, select the webhook events you want to receive.

5. Click Create.

Your webhook endpoint must confirm successful receipt with a 2xx status code within 15 seconds. All timeouts or response codes >=3xx indicate failure, and we will retry. Maple stops retrying after the 8th attempt. Maple disables your endpoint after five days without receiving any 2xx status codes from your endpoint.

Your endpoint must return a 2xx status code quickly, even as your server receives many events in parallel. Therefore, Maple recommends immediately queuing events using SQS, RabbitMQ, or similar, returning a 200, and then processing the event asynchronously.

Verifying events using webhook signatures

Maple signs webhook events using a unique signing secret before sending them to your endpoint. You should verify the event before decoding the body.

To access your signing secret:

1. From your Maple account, navigate to the Agency View.

2. From Settings, click Integration API and access the Webhooks tab.

   

3. From the Endpoints tab, select your endpoint.

4. To the right, click the eyeball icon to show your signing secret.

   

caution

Your webhook signing secret is sensitive and must be kept secure at all times.

SDKs contain helpers to verify webhook events, given the body, headers, and your secret. For example, sdk-node provides isWebhookValid. If you are not using an SDK, see this documentation.

Once verified, the following is an example of the webhook event body.

{
  "data": {
    "attributes": {
      "created": "2023-01-01T12:00:00.000Z",
      "topic": "shift.available"
    },
    "id": "[WEBHOOK_EVENT_ID]",
    "relationships": {
      "resource": {
        "data": {
          "id": "[SHIFT_ID]",
          "type": "shift"
        },
        "links": {
          "related": "shifts/[SHIFT_ID]"
        }
      }
    },
    "type": "webhook-event"
  }
}

Avoiding getting out of sync

Events contain minimal information for security and to avoid including stale data. To avoid getting out of sync with Maple:

• Upon receiving a webhook event, retrieve the latest resource by making a GET call to the URL provided in the data.resource.links.related field.
• Implement idempotent webhook endpoints.

Assume the scheduler makes a shift available and immediately deletes it. Your platform will be out of sync if you insert the shift into your database when handling the shift.available event without verifying the shift's status using the Maple API.

Due to the nature of HTTP, Maple cannot guarantee:

• Ordering: you may receive webhook events out-of-order.
• Exactly-once delivery: you may receive the same webhook event more than once. To handle this, you can store the data.id in your database after successfully handling the event. Then, when receiving events, check your database to see if you have already processed the data.id. If yes, you can safely ignore it.

Event types

Name	Description
shift.available	A shift is available to the agency. The agency should create a shift in its system and make it available to its workers.
shift.unavailable	A shift is unavailable (e.g., canceled or assigned to internal staff). The agency should make the shift unavailable to its workers.
shift.unassigned	The scheduler removed the agency worker from the shift. The agency should remove the worker, but the shift is still available.
shift.updated	A shift is updated on Maple. The agency should get the shift and update it on their side.
shift.backfill	Sent for onboarding and recovery.
facility.enabled	A facility enabled the integration with your agency on Maple. The agency should enable the integration on its platform for the given facility
facility.disabled	A facility disabled the integration with your agency on Maple. The agency should disable the integration on its platform for the given facility

You can also find all available events and payloads on the "Event Catalog" tab.

Retry schedule

Retry number	Interval relative to last retry	Time relative to original attempt
1	Immediately	0 secs
2	5 secs	5 secs
3	5 mins	5 mins, 5 secs
4	30 mins	35 mins, 5 secs
5	2 hrs	2 hrs, 35 mins, 5 secs
6	5 hrs	7 hrs, 35 mins, 5 secs
7	10 hrs	17 hrs, 35 mins, 5 secs
8	10 hrs	27 hrs, 35 mins, 5 secs