February 25, 2022
Back to Documents
February 25, 2022
Webhooks
Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook at Yeti, users configure a webhook listener and subscribe to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages that are triggered when events occur. Yeti logs each notification message that it delivers to your webhook listener.
Webhooks are asynchronous, their order is not guaranteed, and idempotency might lead to a duplicate notification of the same event type.
Important: If your webhook endpoint is unavailable or takes too long to respond, Yeti resends the notification message 3 times until a successful response is given.
How to use webhooks in Yeti?
- Contact support@yetisnow.com to request permission to use webhooks.
- When you have access to webhooks, you will see this icon when you click on the gear.
3. You will see two fields: “token” and “ended”.
The “token” field is an option for you to store the token you created; however, you can leave it blank.
In the “ended” field, you will need to enter the address of your application.
Logs
All triggered events, even those that did not succeed, will be stored in logs.
The logs can be accessed through the button next to the text field where you will add your endpoint. See the image below.
In the body of each log, you will see the values that were sent to your endpoint in JSON format.
Just below the body, you will see more information about the request: the time it was sent and also the status of the request.
The status is usually the status code of the HTTP request, but it can also be an exception. For example, an issue due to a security certificate (HTTPS).
The list of attempts is sorted from most recent to oldest.
Events
Site Performance Ended
This event will be triggered in all places where there is a possibility to end a Site visit (Site Performance) started by the Operator on the mobile app.
End Site Performance on the mobile app:
- Site Performance screen by itself;
- End of Route – All in-progress Sites that are within this Route will be ended;
- End of a Shift – All in-progress Sites that are within this Shift will be ended.
End (close) Site Performance on the web application, on the Dispatch page. When a dispatcher closes a Shift, a Route, or the Site itself that is in progress, the event will be triggered.
Sample Message Payload
The sample here is a notification that lets your app know a Site visit occurred.
{
"event": "site_performance_ended", // string
"site_performance": { // object
"id": null, // integer
"notes": null, // string
"approved": null, // boolean
"last_geofence_triggered_at": null, // string - datetime (UTC)
"first_geofence_triggered_at": null, // string - datetime (UTC)
"basic_view": false, // boolean
"snow_depth": 0,
"temperature": null, // numeric
"dispatcher_notes": null, // string
"weather_condition": null, // object
"started_at": "2022-10-21T17:39:36.000000Z", // string - datetime (UTC)
"ended_at": null, // string - datetime (UTC)
"site": { // object
"id": null, // integer
"city": null, // string
"name": null, // string
"address": null, // string
"latitude": null, // numeric
"longitude": null, // numeric
"map_icon": null, // string enum ('circle', 'polygon', 'square', 'star', 'triangle')
"basic_view": false, // boolean
"complement": null, // string
"postal_code": null, // string
"site_reference": null, // string
"client_reference": null // string
},
"operators": [ // array of objects
{
"id": null, // integer
"name": null, // string
"email": null, // string
"phone": null, // string
"avatar_url": null, // string - url
"phone_code": null, // integer
"deleted_at": null, // string - datetime (UTC)
"shift": { // object
"id": null, // integer
"notes": null, // string
"leader_shift_id": null, // integer
"started_at": null, // string - datetime (UTC)
"ended_at": null, // string - datetime (UTC)
},
"user_company": { // object
"id": null, // integer
"rate": null, // numeric
"employee_code": null // string
},
"service_performances": [ // array of objects
{
"id": null, // integer
"deleted_at": null, // string - datetime (UTC)
"service": { // object
"id": null, // integer
"name": null, // string
"color": null, // string - hexadecimal
},
"equipment_category_performances": [ // array of objects
{
"id": null, // integer
"duration_hours": null, // numeirc duration - Example 2h:30min will be here as 2.5, for the same site visit duration it will be -1.
"category": { // object
"name": null, // string
},
"equipment_performances": [ // array of objects
{
"id": null, // integer
"duration_hours": null, // numeirc duration - Example 2h:30min will be here as 2.5, for the same site visit duration it will be -1.
"equipment": { // object
"id": null, // integer
"name": null, // string
"name_for_operators": null, // string
}
}
]
}
],
"consumable_category_performances": [ // array of objects
{
"id": null, // integer
"quantity": null, // numeric
"category": { // object
"name": null // string
}
}
]
}
]
}
],
"contractor": { // object
"id": null, // integer
"code": null, // string
"name": null, // string
"logo_url": null // string - url
},
"sub_contractor": { // object
"id": null, // integer
"code": null, // string
"name": null, // string
},
"ground_condition": { // object
"id": null, // integer
"name": null // string
},
"route_performance": { // object
"id": null, // integer
"shift_id": null, // integer
"started_at": null, // string - datetime (UTC)
"ended_at": null, // string - datetime (UTC)
"route": { // object
"id": null, // integer
"name": null, // string
"notes": null, // string
"season": "all", // string enum ('all', 'summer', 'winter')
"company_id": null, // integer
"scheduled_for": null, // string - datetime (UTC)
"estimated_hours": null, // numeric
"template_route_id": null, // integer
"display_to_operator": true, // integer
"created_at": null, // string - datetime (UTC)
"updated_at": null, // string - datetime (UTC)
}
},
"photo_performances": [ // array of objects
{
"id": null, // integer
"url": null, // string url
"when": null // string enum ('before', 'after')
},
]
}
}
Message Detailed
| event | string | Webhook event key. | |||
| site_performance | object | Object with the information of the Site visit. | |||
| site | object | Basic Site information. | |||
| id | integer | Unique identifier of the Site visit. | |||
| notes | string | Operator notes on field. | |||
| approved | boolean | Site approval status. It will always be sent null because the record still needs to pass the dispatch page after it has been ended. | |||
| started_at | datetime | When the Site visit started. | |||
| ended_at | datetime | When the Site visit ended. | |||
| basic_view | boolean | What was the view on the Site screen when the Site was ended. | |||
| snow_depth | decimal | Height of snow in centimeters. | |||
| temperature | decimal | Temperature in Celsius. | |||
| dispatcher_notes | string | Dispatcher notes while the Site was performing. | |||
| first_geofence_triggered_at | datetime | First time the site geofence was fired. | |||
| last_geofence_triggered_at | datetime | Last time the site geofence was fired. | |||
| ground_condition | object | Ground condition. | |||
| weather_condition | object | Weather condition. | |||
| photo_performances | array of objects | List of photos taken in the field. | |||
| id | integer | Unique image identifier. | |||
| url | string | URL of the picture. | |||
| when | string | Identification when the photo was taken, “before” or “after”. | |||
| crew | array of objects | List of Users who were together when the Site visit occurred. | |||
| shift | object | User shift information. | |||
| id | integer | Unique Shift ID. | |||
| notes | string | Operator notes at the end of its Shift. | |||
| started_at | datetime | When the user’s shift started. | |||
| ended_at | datetime | When the user’s shift ended. | |||
| leader_shift_id | integer | Shift identification of who is the leader. | |||
| user_company | object | Link between the User and the Company. | |||
| id | integer | Unique ID of the relationship between User and Company. | |||
| rate | decimal | User’s rate per hour. | |||
| employee_code | string | Employee ID. | |||
| service_performances | array of objects | List of Services performed in the field. | |||
| id | integer | Unique Service performed ID. | |||
| operator_id | integer | User ID related to the Service. | |||
| service | object | Service basic information. | |||
| equipment_performances | array of objects | Equipment performed in the field. | |||
| id | integer | Unique piece of equipment used in the field. | |||
| duration_hours | decimal | Duration in hours of the equipment used. When its value is “-1”, it is an indicator that the time of use of the equipment was the same time that the visit to the site took. | |||
| equipment | object | Basic piece of equipment information. | |||
| category | object | Basic equipment category information. | |||
| route_performance | object | Route performance information when the event occurred. | |||
| id | integer | Unique ID of the Route Performance. | |||
| started_at | datetime | When the Route was started. | |||
| ended_at | datetime | When the Route was ended. | |||
| shift_id | integer | Crew leader’s unique Shift ID. | |||
| route | object | Basic Route information. It is for a regular route or a dispatched route. | |||
