Updated: 2024-09-01

Overview

This document outlines the use and implementation of our webhook, which notifies your system of events in real-time. To ensure the security and integrity of the data, each webhook request includes an HMAC signature for verification. Arya uses a self hosted hook0 instance  to manage all webhooks.

Security and Verification

To verify that each request comes from a trusted source, we use HMAC with SHA-256 hash function to generate a signature of the request payload. This signature is included in the request headers. Your endpoint should validate this signature before processing the webhook data. A secret key will be generated for you at the time of the webhook registration.

Documentation for the verification process is available at https://documentation.hook0.com/docs/verifying-webhook-signatures

Headers

The POST request will have the following headers always sent as a part of the request.

{

{
x-event-id: <webhook-event-id>[uuid]
x-event-type: <webhook-event-type>[string]
x-hook0-signature: <webhook-event-signature>[t=timestamp,v0=sha256-hash]
}

// Headers Example.
{
x-event-id: 803351d7-bcd1-416b-8955-0377a0b19976
x-event-type: schedule.event.created
x-hook0-signature: t=1725314130,v0=abec171bbc7587a82263a17592d84395ad7147904d76f098c1d1d2f49048ba1a
}

Data Structure

The POST request will have data structured in the following way:

{
	id: uuid, // webhook instance that was sent out.
	scope: string, // "schedule"
	type: string, // "created" | "edited" | "deleted"
	timestamp: datetime,
	data: [
		// ... dependent on the data type being sent.
]
}

// Data example:
// Schedule: [ created / updated ]
[
    {
        "id": "c4d2b16e-1d1e-40a1-acb8-c165d1ed3b19", // UUID
        "entity": {
            "name": "Some Entity Name", // String
            "location": "Some Entity Location" // String
        },
        "title": "Some Title", // String
        "description": "Some Description", // String
        "startTime": "2024-01-17T05:45:00.291Z", // UTC ISO String
        "endTime": "2024-01-17T07:45:00.291Z", // UTC ISO String
        "type": "shift", // "shift" | "pto" | "availability"  - String
        "timezone": "America/New_York", // Timezone String
        "parentId": "c4d2b16e-1d1e-40a1-acb8-c165d1ed3b19", // UUID
	 "jobRoleCategory": {
"id": "5c6a6377-6738-47d3-aa99-fa4cdd793e3d", // UUID
"name": "Some Category Name" // String
	  },
	 "jobRoleTitle": {
"id": "ec6d53c7-3c56-4c12-856d-a26a8411a13a", // UUID
"title": "Some Job Title" // String
  }
        "allDay": false, // Boolean
        "tags": [  // Array<String>
            "tag 1", "tag 2"
        ],
        "employee": {
            "email": "[email protected]", // Email String as identifier.
            "firstName": "John", // String
            "lastName": "Doe", // String
        },
        "recurrence": {
            "rule": "RRULE:FREQ=WEEKLY;INTERVAL=1" // RRULE String
        }
    }
]

// Schedule: [ deleted ]
[
    {
        "id": "c4d2b16e-1d1e-40a1-acb8-c165d1ed3b19"
    }
]

Event Types:

Arya webhooks are currently restricted to schedules. The webhook is triggered on create , update and delete events.

create and update events send the same payload (this is subject to change with a notice period). Delete events only send the id that was deleted.

Notes:

Ensure that the secret key used for generating the HMAC signature in your system is kept secure and not exposed in your codebase or version control.

The signature verification step should be one of the first checks in your webhook handler to prevent processing requests with invalid signatures.

Editing a schedule event in the middle of a recurrence updates the parent schedule item’s recurrence field with an exception and creates a new schedule item in place of the edited schedule item. Eg (adds one exception to april 12th 2024):