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"
}