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.
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:
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_tEKaaKYgqLcRNQAGD3-O7wAAAA==", "changeType" : "updated" }, { "id" : "AQMkAGY0ZTQyM2ZlLTM5N2UtNGZkYy1hZmQ2LTJkNDdmNTlmMGZlNgBGAAADhXGu-WVhvEKOWPBUZKnvPwcAAAAUsezTfrRCmmimIKi3ETUAAAIBDAAAARSx7NN_tEKaaKYgqLcRNQAGD3-S2QAAAA==", "changeType" : "created" } ] }
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}