Yoxel Webhooks API
Webhooks allow your application to receive simple notifications when certain events occur. They essentially tell your application that it can run incremental syncs to obtain the changed records (updated/deleted). ## Prerequisites Gmail notifications require a special configuration, explained in [this article](https://developers.google.com/gmail/api/guides/push). A PubSub PUSH subscription should specify your Aurinko endpoint `https://{yourAurinkoDomain}/push/google/email` so that Gmail notifications are delivered to Aurinko first. Once the PubSub subscription is configured and the `publish` rights are granted to `gmail-api-push@system.gserviceaccount.com` please specify your PubSub topic in the Application settings (Google OAuth) in the Aurinko portal. ## Notification URL verification To ensure that notifications are being delivered to a server under your direct control, we must verify your ownership by issuing you a challenge request. Please make sure your notification endpoint (specified in the notificationUrl property) responds to a validation request. If validation fails, the request to create the subscription returns a 400 Bad Request error. 1. Aurinko sends a POST request to the notification URL: ``` Content-Type: text/plain; charset=utf-8 POST https://{notificationUrl}?validationToken={challenge} ``` 2. The client must provide a response: * A 200 (OK) status code. * The body must include the validation token provided by the validationToken query parameter ## Notifications Aurinko sends notifications as POST requests with the following json payload: ``` { "subscription" : integer, // subscription Id "resource" : string, "accountId": integer, "error": string, // if any "lifecycleEvent": string, // Enum of `error` or `active`, when subscription state changes "payloads" : [...] } ``` You notification endpoint should respond with the 200 (OK) status code when a notification is successfully processed. ### Notification validation Aurinko signs its requests using a secret unique to your app. Here's an overview of the process to validate a signed request from Aurinko: 1. Retrieve the `X-Aurinko-Request-Timestamp` header on the HTTP request, and the body of the request (Use the raw request body, before it has been deserialized from JSON or other forms.). 2. Concatenate the version number, the timestamp, and the body of the request to form a basestring. Use a colon as the delimiter between the three elements. The version number right now is always `v0`. ``` final byte[] signData = org.apache.commons.lang3.ArrayUtils.addAll( ("v0:" + timestampSeconds + ":").getBytes(StandardCharsets.UTF_8), payloadBytes ); ``` 3. With the help of HMAC SHA256 implemented in your favorite programming language, hash the above basestring, using the Aurinko Signing Secret as the key. 4. Compare this computed signature to the `X-Aurinko-Signature` header on the request. If it matches - request is valid, if not - request must be discarded.