Aurinko
Aurinko websiteAurinko blogAPI ReferenceContact Support
Aurinko API
Aurinko API
  • Getting started
    • What is Unified Mailbox API?
    • Getting started with Aurinko
    • Get your developer API keys
    • Adding Aurinko to Google Workspace allowlist
    • Bubble.io plugin
    • Team members and roles in applications
  • Unified APIs
    • Email API
    • Calendar API
    • Contacts API
    • Tasks API
    • Webhooks API
      • Configuring Pub/Sub for Gmail API Webhooks
    • Direct API
  • Authentication
    • OAuth Flow
      • Account OAuth Flow
      • User ОАuth Flow
      • Service Account OAuth Flow
    • Authentication scopes
    • Authorized return URLs
    • Google OAuth setup
    • Office 365 OAuth setup
    • ZOHO OAuth setup
    • Service accounts
      • Setting up G Suite service account
      • Setting up Office 365 daemon app registration
  • Scheduling
    • Create your first appointment booking page
    • Calendar Booking Page
    • Booking API
    • Group Booking API
  • Workspace Addons
    • Outlook addins
      • Create your first Outlook addin
      • Office 365: Installing Outlook addin
    • Microsoft Teams apps
      • Microsoft Teams bot setup
      • Create your first MS Teams app
      • Installing MS Teams app
    • Chrome Extensions with Google authentication
    • Google Workspace Add-Ons
  • Dynamic API
    • What is Dynamic (Virtual) API?
    • Getting Started with Dynamic API
Powered by GitBook
On this page
  • Aurinko Webhooks API
  • Aurinko account setup
  • Setting up a Webhook
  • Authentication
  • API Resources
  • Subscribing
  • Payloads
  • Handling Webhooks
  • Retries
  • Lifecycle events
  • Deleting a webhook
  1. Unified APIs

Webhooks API

Aurinko's Webhooks API enables real-time event notifications for email, calendar, contacts, and task updates by subscribing to specific resources and handling webhook payloads efficiently.

PreviousTasks APINextConfiguring Pub/Sub for Gmail API Webhooks

Last updated 1 month ago

Aurinko Webhooks API

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.

Aurinko account setup


First, create your account in the , then follow the guide to .

Setting up a Webhook


  1. Prepare an endpoint URL on your server.

  2. Provide this endpoint to our system through the process.

  3. Ensure your endpoint can handle POST requests and supports the initial

  4. To leverage native Gmail push notifications .

Authentication


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


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,
            "context" : "",
            "trackingCode": "5c59753a-3e4f-4c2c-a2f7-1e5c4fc538d2"
        },
        {
            "id": 1687,
            "createdAt": "2023-09-29T10:59:20.236665Z",
            "eventType": "open",
            "location" : "",
            "userAgent": "Mozilla/4.0 (compatible; ms-office; MSOffice 16)",
            "remoteAddr": "176.116.84.4",
            "trackingId": 1617,
            "context" : "",
            "trackingCode": "fce4d887-1aea-4b2f-93fc-5e02147f9c3d"
        }
    ]
}

{
    "subscription" : 3223,
    "resource" : "/email/tracking",
    "accountId" : 1464,
    "payloads" : [
        {
            "id" : 5973,
            "createdAt" : "2024-10-23T17:15:57Z",
            "eventType" : "replyBounce",
            "threadId" : "",
            "messageId" : "",
            "internetMessageId" : "<...@mail.gmail.com>",
            "trackingId" : 3230,
            "context" : "",
            "trackingCode" : "bce0e37e-9f90-4171-9f76-926c77b2c9b1"
        }
    ]
}

When an email is first processed for tracking, an ‘Initial’ event is triggered. This event occurs only once when tracking begins, typically upon sending the email, and is not included in subsequent tracking updates:

{ 
    "subscription" : 3190, 
    "resource" : "/email/tracking", 
    "accountId" : 1535, 
    "payloads" : [ 
        { 
            "id" : 5822, 
            "createdAt" : "2024-10-17T13:35:04Z", 
            "eventType" : "initial", 
            "threadId" : "", 
            "messageId" : "", 
            "internetMessageId" : "<...@mail.gmail.com>", 
            "trackingId" : 3159, 
            "context" : "", 
            "trackingCode" : "e2d9e1fb-e1b2-4a57-96d9-5bc0fe10b129" 
        } 
    ] 
}

Handling Webhooks


When you receive a webhook:

  1. Validate the signature to ensure it's from the Aurinko platform.

  2. Respond with a 200 OK as quickly as possible.

  3. 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}

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 ). The signing secret can be found on your app's dashboard page:

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

Aurinko portal
get Your Developer API Keys
event subscription
url verification step.
Configure Cloud Pub/Sub
Notification Validation
subscriptions endpoint