# Yoxel Webhooks API

**Canonical:** https://apis.io/apis/aurinko/aurinko-webhooks-api/  
**Provider:** Yoxel — https://apis.io/providers/aurinko/  
**Base URL:** https://api.aurinko.io  
**Documentation:** https://apirefs.aurinko.io/

Yoxel Webhooks API is one of 25 APIs that [Yoxel](https://apis.io/providers/aurinko/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include Webhook. The published artifact set on APIs.io includes an OpenAPI specification and 6 JSON Schemas.

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.

## Operations (4)

| Method | Path | Summary |
|---|---|---|
| POST | `/v1/subscriptions` | Create a push event subscription |
| GET | `/v1/subscriptions` | Get a list of push event subscriptions |
| GET | `/v1/subscriptions/{id}` | Check a subscription status |
| DELETE | `/v1/subscriptions/{id}` | Remove a subscription |

## Machine-readable artifacts (7)

- **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/aurinko/refs/heads/main/openapi/aurinko-webhooks-api-openapi.yml
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/aurinko/refs/heads/main/json-schema/aurinko-email-message-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/aurinko/refs/heads/main/json-schema/aurinko-group-booking-out-dto-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/aurinko/refs/heads/main/json-schema/aurinko-booking-out-dto-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/aurinko/refs/heads/main/json-schema/aurinko-group-booking-in-dto-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/aurinko/refs/heads/main/json-schema/aurinko-group-booking-update-dto-schema.json
- **JSONSchema** — https://raw.githubusercontent.com/api-evangelist/aurinko/refs/heads/main/json-schema/aurinko-booking-in-dto-schema.json

## Other Yoxel APIs (12)

- [Yoxel Account API](https://apis.io/apis/aurinko/aurinko-account-api/)
- [Yoxel Accounts API](https://apis.io/apis/aurinko/aurinko-accounts-api/)
- [Yoxel Auth API](https://apis.io/apis/aurinko/aurinko-auth-api/)
- [Yoxel Availability API](https://apis.io/apis/aurinko/aurinko-availability-api/)
- [Yoxel Booking API](https://apis.io/apis/aurinko/aurinko-booking-api/)
- [Yoxel Calendars API](https://apis.io/apis/aurinko/aurinko-calendars-api/)
- [Yoxel Cal Sync API](https://apis.io/apis/aurinko/aurinko-calsync-api/)
- [Yoxel Contacts API](https://apis.io/apis/aurinko/aurinko-contacts-api/)
- [Yoxel Cont Sync API](https://apis.io/apis/aurinko/aurinko-contsync-api/)
- [Yoxel Drafts API](https://apis.io/apis/aurinko/aurinko-drafts-api/)
- [Yoxel Email Folders API](https://apis.io/apis/aurinko/aurinko-emailfolders-api/)
- [Yoxel Email Sync API](https://apis.io/apis/aurinko/aurinko-emailsync-api/)

## Tags

Webhook

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/aurinko/aurinko-webhooks-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/aurinko/.