Yardman Help

Always up-to-date User's Manual and Documentaion for Developers

Yardman Logo

Getting started with Webhooks

Webhooks allow external services to be notified when certain events happen. When the specified events happen, we’ll send a POST request to each of the URLs you provide.

Once installed, the webhook will be triggered each time one or more subscribed events occurs. You can create unlimited number of webhooks for each event.

Webhooks can be used to update external applications, trigger some external events, make data updates and much more. You’re only limited by your imagination.

Events

When configuring a webhook, you can choose which events you would like to receive payloads for. Only subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server. You can change the list of subscribed events through the UI anytime.

Each event corresponds to a certain set of actions that can happen to your yard resource. For example, if you subscribe to the booking_created event you’ll receive detailed payloads every time a booking is created.

The available events are as follows.

Event Type Trigger
booking_created any time a Booking is created
booking_updated any time a Booking is updated
booking_deleted any time a Booking is deleted
visit_created any time a Visit is created
visit_updated any time a Visit is updated
visit_deleted any time a Visit is deleted
person_created any time a Person is created
person_updated any time a Person is updated
person_deleted any time a Person is deleted
company_created any time a Company is created
company_updated any time a Company is updated
company_deleted any time a Company is deleted
vehicle_created any time a Vehicle is created
vehicle_updated any time a Vehicle is updated
vehicle_deleted any time a Vehicle is deleted

Payloads

Each event has a similar JSON schema, but a unique payload object that is determined by its event type. In addition to the fields relevant for each event, webhook payloads include the event_name field with documented event type name.

Delivery headers

HTTP POST payloads that are delivered to your webhook’s configured URL endpoint will contain several special headers:

Header Description
X-Yardman-Event Name of the event type that triggered the delivery.
X-Yardman-Delivery A GUID to globally identify the delivery.
X-Yardman-Signature The HMAC hex digest of the response body. This header will be sent if the webhook is configured with a secret. The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key.

The User-Agent for the requests will have the prefix Yardman-Hookshot/.

Sample delivery

POST /payloads HTTP/1.1
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
User-Agent: Yardman-Hookshot/1.17.1
Content-Type: application/json
X-Yardman-Event: booking_created
X-Yardman-Delivery: e310c6c9-dac1-471e-a628-0b3c78d9b6aa
X-Yardman-Signature: sha1=4e696a7fb6f5ddc7f67274c5f350dc8fef5ba4fb
Connection: close
Host: 880af687.ngrok.io
Content-Length: 744
X-Forwarded-Proto: https
X-Forwarded-For: 2a01:4f8:13b:2d45::2
{
    "booking": {
        "id": 805,
        "confirmation_code": "KGK2E2",
        "check_in_at": "2018-11-30T15:50:00.000+01:00",
        "active": true,
        "notes": "",
        "yard": {
            "id": 25,
            "name": "Hane Court",
            "location": {
                "id": 19,
                "name": "Emmerichfort"
            }
        },
        "bookable": {
            "type": "person",
            "person": {
                "id": 62,
                "first_name": "Michelle",
                "last_name": "Sauer",
                "driving_license_number": null,
                "mobile_phone": null,
                "email": null,
                "notes": null,
                "status": "unknown"
            }
        },
        "movement_plan": {
            "id": 36,
            "name": "Others 2h",
            "properties": null,
            "yard": {
                "id": 25,
                "name": "Hane Court"
            },
            "checkpoints": [
                {
                    "id": 105,
                    "estimated_arrival_in": 900,
                    "estimated_departure_in": 300,
                    "area": {
                        "id": 55,
                        "name": "Entry Gate"
                    }
                },
                {
                    "id": 106,
                    "estimated_arrival_in": 7200,
                    "estimated_departure_in": 300,
                    "area": {
                        "id": 58,
                        "name": "Exit Gate"
                    }
                }
            ]
        }
    },
    "event_name": "booking_created"
}

Yardman, our YMS Software