Yoobic Webhooks API

You can create webhooks with HTTP targets to build integrations with the services or with your back-end system. Examples:- Alert your team in Slack when a mission is created- Pass mission to your docs team in Asana after a mission is completed- Update Salesforce when a new store is createdAn HTTP target lets you pass information to third-party services and REST APIs that accept JSON in HTTP requests.The list of topics supporting webhooks are:- campaigns- courses- events- files- lessons- mission-workflows- missions- mission-comments- mission-services- store-types- stores- users- visits- webhooks- For visits, the `delete` action is not supported. To receive deleted visit objects you need to subscribe to the `missions` topic. The deleted visits are sent as their corresponding `mission` object as a visit is a sub-type of missions.- For mission-comments, only `create` and `update` actions are supported. See example use case [here](https://yoobic.zendesk.com/hc/en-gb/articles/14909941328274-Ticketing-System-Integration-Setup-Guide-Synchronise-Requests-and-Comments-With-External-Tickets#h_01HEJEZ7VEZSGHBCZH7C569T8A).- For mission-services, only `create` and `update` actions are supported. See example use case [here](https://yoobic.zendesk.com/hc/en-gb/articles/14909941328274-Ticketing-System-Integration-Setup-Guide-Synchronise-Requests-and-Comments-With-External-Tickets#h_01HEJCJBH9B9G62R79FBGKA29N).- If the webhook has a filter, the webhook will fire only once per object when it matches the filter the first time. For example, if the webhook is on topic `missions` , operations `update` and the filter is `{"status": "finished"}`, then each mission will trigger a new message only when it is `finished`. If another update happens later, to validate the mission for example, it will not fire a new message.- To send multiple messages for the same object and operation, set `trigger_on_every_match` to true. For example if you want to track every update for `mission-workflows` for every step of the workflow.- On mission-workflows, possible to filter on `step_title` and `state`. Both can be used together to **only** fire the webhook when a step is reached. Otherwise, having only a filter on `step_title` results in the webhook firing twice when the step is reached due to the mission being updated when it is assigned to a user.- The object output of mission-workflows contains the same fields as for a regular mission, with an addition of `workflow_step_title`, `workflow_step_id` and `workflow_state`.#### ErrorsIf a webhook fails it becomes inactive. In addition a failure object with the http status and reason are set on the webhook's object.``` { "is_active": false", "error": { "status": 404, "message": "Not Found." } } ```Once the webhook becomes active again, the error object will be cleared. i.e. a PATCH request to fix the broken webhook:``` { "is_active": true, "url": "" } ```#### Callback response bodyThe callback url will have the following fields -- action: create/update/delete- topic: one of the supported topics i.e. store-types- data: the actual entity- updatedFields: list of fields that were updated ``` { "action": "update", "topic": "store-types", "data": { "store_type_id": "56b0c262e9a22a4e5f02be7d", "name": "ice-cream", "group_ids": ["managers"], "created_date": "2016-02-02T14:51:14.644Z", "updated_date": "2020-07-15T14:18:41.750Z" }, "updatedFields": [ "group_ids" ] } ```#### SecurityWebhooks provide an additional security measure to verify that the webhook is genuine and has come from YOOBIC. This can be useful if you're looking to ensure only YOOBIC webhooks are being made to your endpoint and ensure the information is genuine and as the system expects. These signatures will also help prevent against replay attacks. Verifying the signing secret is optional. When registering a webhook you can set an additional `secret` field in the payload. Webhook requests will contain two headers which can be used to verify the request's authenticity:- `x-yoobic-webhook-signature` - the main signature- `x-yoobic-webhook-signature-timestamp` - the timestamp used to verify the signature This is used in conjunction with the payload of the request (if there is one). Verifying the signature Sign the body and signature timestamp with the webhook secret key using SHA256, then base64 encoding the resulting digest. Represented simply: base64(HMACSHA256(TIMESTAMP + BODY)) To verify the signature, create the same SHA256 HMAC signature and then compare it to the webhook payload to ensure that they match. If they match, then you can be sure that the webhook came from YOOBIC. If they don't, it may be a request from another source. Here is an example of a verification signature function in nodejs ```js const crypto = require('crypto'); const SIGNING_SECRET = function isValidSignature(signature, body, timestamp) { let hmac = crypto.createHmac('sha256', SIGNING_SECRET); let sig = hmac.update(timestamp + body).digest("base64"); return ( Buffer.compare( Buffer.from(signature), Buffer.from(sig.toString("base64")) ) === 0 ); } // assuming you have access to the HTTP request (req) object your webhook endpoint has been called with const signature = req.headers["x-yoobic-webhook-signature"]; const timestamp = req.headers["x-yoobic-webhook-signature-timestamp"]; const raw_body = JSON.stringify(req.body); const isValid = isValidSignature(signature, raw_body, timestamp) if (isValid) { console.log("HMAC signature is valid"); } else { console.log("HMAC signature is invalid"); } ```#### Webhooks and sandboxYou can create webhooks in the sandbox environment but they are automatically removed every week when the sandbox environment is refreshed. Active webhooks in production are not copied to the sandbox environment during the weekly sandbox refresh.### Fields| Field | Type | Required | Readonly | OrderBy | Description ||----------------------|:--------------:|:--------:|:--------:|:-------:|---------------------------||`webhook_id` | string | | x | | Unique webhook id ||`url` | string | x | | | Unique http target url ||`topics` | array | | | | A list of entities to listen for (default: all)||`operations` | array | | | | A list of operations to listen for ["create", "update", "delete"] (default: all)||`is_active` | boolean | | | | enable or disable this webhook (default: true) ||`trigger_on_every_match`| boolean | | | | Specifies if an object should trigger the webhook on every match or only once ||`has_secret` | boolean | | x | | True if secret has been provided ||`error` | object | | x | | A description object (http status, message) to the reason this webhook is inactive ||`secret` | string | | | | Encryption key ||`created_date` | date | | x | | Creation date ||`updated_date` | date | | x | x | Last update date |