Webhooks API - Aurinko Support

Webhooks allow your apps to receive real-time updates from the Aurinko platform. By registering a webhook URL, you can get notified when specific events happen.

Setting up a Webhook

Prepare an endpoint URL on your server.
Provide this endpoint to our system through the event subscription process.
Ensure your endpoint can handle POST requests and supports the initial url verification step.
To leverage native Gmail push notifications Configure Cloud Pub/Sub.

Authentication

Webhooks are secured using a shared secret that is used to generate a signature. The signature is sent in the HTTP header of each request, allowing you to verify the authenticity (see Notification Validation). The signing secret can be found on your app’s dashboard page:

Image Placeholder

API Resources

The Aurinko webhook events are associated with API resources (parts of the API) and subscriptions are created for those resources. Here is the list of available API resources:

/email/messages - events representing mailbox changes
/email/tracking - events representing email tracking changes
/calendars/primary/events, /calendars/{calId}/events - events representing calendar changes
/contacts - events representing address book changes
/tasklists/default/tasks, /tasklists/{tlId}/tasks - events representing todo item changes

Subscribing

To create a new subscription POST a resource and a notification url to the subscriptions endpoint:

curl -H 'Authorization: Bearer <access token>' \
    -X POST https://api.aurinko.io/v1/subscriptions \
    -d '{
        "resource": "/email/messages",
        "notificationUrl": "https://myserver/pushEvents"
}'

Response:

{ 
    "id": "87665448354",
    "resource": "/email/messages", 
    "notificationUrl": "https://myserver/pushEvents" 
}

Payloads

Each API resource may have its own payload format. Below is a sample payload that is common for email/messages, /contacts, /calendars/{id}/events, /tasklists/{id}/tasks:

{
    "subscription" : 1217,
    "resource" : "/email/messages",
    "accountId" : 1532,
    "payloads" : [
        {
            "id" : "AQMkAGY0ZTQyM2ZlLTM5N2UtNGZkYy1hZmQ2LTJkNDdmNTlmMGZlNgBGAAADhXGu-
                   WVhvEKOWPBUZKnvPwcAAAAUsezTfrRCmmimIKi3ETUAAAIBCQAAARSx7NN\_tEKaaKY
                   gqLcRNQAGD3-O7wAAAA==",
            "changeType" : "updated"
        },
        {
            "id" : "AQMkAGY0ZTQyM2ZlLTM5N2UtNGZkYy1hZmQ2LTJkNDdmNTlmMGZlNgBGAAADhXGu-
                   WVhvEKOWPBUZKnvPwcAAAAUsezTfrRCmmimIKi3ETUAAAIBDAAAARSx7NN\_tEKaaKY
                   gqLcRNQAGD3-S2QAAAA==",
            "changeType" : "created"
        }
    ]
}

Next, an example of the email/tracking events (eventType can be open, reply, or bounce):

{
    "subscription": 1271,
    "resource": "/email/tracking",
    "accountId": 1626,
    "payloads": [
        {
            "id": 1670,
            "createdAt": "2023-09-29T09:13:44Z",
            "eventType": "reply",
            "threadId": "",
            "messageId": "",
            "internetMessageId": "<...@mail.gmail.com>",
            "trackingId": 1614,
            "trackingCode": "5c59753a-3e4f-4c2c-a2f7-1e5c4fc538d2"
        },
        {
            "id": 1687,
            "createdAt": "2023-09-29T10:59:20.236665Z",
            "eventType": "open",
            "userAgent": "Mozilla/4.0 (compatible; ms-office; MSOffice 16)",
            "remoteAddr": "176.116.84.4",
            "trackingId": 1617,
            "trackingCode": "fce4d887-1aea-4b2f-93fc-5e02147f9c3d"
        }
    ]
}

Handling Webhooks

When you receive a webhook:

Validate the signature to ensure it’s from the Aurinko platform.
Respond with a 200 OK as quickly as possible.
Process the event data asynchronously.

Retries

If your endpoint responds with any HTTP status other than 200 OK or 422 Unprocessable, Aurinko will attempt to resend the webhook 1, 2, 4, 8 … etc seconds (the interval won’t increase beyond 10mins). Responding with the 422 HTTP status results in removing the subscription.

Lifecycle events

If for some reason your webhook subscription becomes problematic (i.e. because account credentials have expired), Aurinko will send a lifecycle event like this:

{
    "subscription" : 1217,
    "resource" : "/email/messages",
    "accountId" : 1532,
    "lifecycleEvent": "error",
    "error": "Error message"
}

When the subscription comes back to life, Aurinko will send:

{
    "subscription" : 1217,
    "resource" : "/email/messages",
    "accountId" : 1532,
    "lifecycleEvent": "active"
}

Deleting a webhook

curl -H 'Authorization: Bearer <access token>' \
    -X DELETE https:/api.aurinko.io/v1/subscriptions/{id}

Knowledge Base