Webhooks
Learn how to get notified of any changes in your users' data.
Webhooks let you stay up-to-date with any new data added, updated, or deleted in real-time. For example, when the user links a new work account, Argyle will immediately call an http endpoint on your system to let you know about the event.
You can find the full list of webhook events in the Webhooks reference.
Argyle webhooks are delivered from two static IP addresses:
35.188.163.115
34.122.50.253
Subscribe to webhooks using the API
The webhook events you subscribe to are delivered for all accounts. Each time a new account is connected or an existing one is updated, a corresponding webhook will notify your system.
You can subscribe to webhooks by sending a POST
request to Argyle's webhooks endpoint with the event name you want to subscribe to. The Webhooks reference contains the list of examples for all webhook subscription calls.
curl -X POST https://api-sandbox.argyle.com/v1/webhooks \
-u api_key_id:api_key_secret \
-H "Content-Type: application/json" \
-d '{"events": ["activities.fully_synced"],
"secret": "<secret for signature verification>",
"name": "name-of-the-webhook",
"url": "https://mybackend.com/callback/argyle"}'
You have to choose a random value for the secret
parameter when subscribing to webhooks. You will use this value during signature validation to determine the authenticity of the webhook.
For example, if you subscribe to the activities.fully_synced
event, every time all activities have finished syncing during the initial scan, the specified url will be invoked with the json
payload specific to that event.
Here is an example payload for activities:
{
"event": "activities.fully_synced",
"name": "Fully synced",
"data": {
"account": "12db5af4-fd5f-4d1f-bd98-0360df770aa8",
"user": "abdb5af4-fd5f-4d1f-bd10-0360df77012c",
"available_from": "2017-07-15T00:00:00",
"available_to": "2019-10-01T15:47:00",
"available_count": 324
}
}
Subscribe to webhooks using Console
Visit the Webhooks tab in the Developers section of Console to view and manage your existing webhook subscriptions as well as create new ones.
Signature validation
You will get a webhook payload body digest in the headers. To verify the authenticity of the webhook payload, you need to digest the received payload body by using HMAC-SHA512
and your secret as a key. Received body must be digested verbatim — no parsing and rerendering before providing bytes to the digest. If your digest matches the one that you received in headers, then the payload is authentic.
Example
For the following body:
{"name": "Account added", "event": "accounts.added"}
the signature header would be:
'X-Argyle-Signature': '13b68c651cdf714d8d00e88d3c9997d2ea2cb6ffcc57ba2d9164af5898169124e75505f354ded4350c96b03b2cddf01cbe71bc26cb2dc656a69ef670bcda0f86'
where the secret to calculate the signature was:
my little secret
Below is an example in Node:
const http = require('http');
const crypto = require('crypto');
const serverPort = 80
const requestListener = function (req, res) {
// the client secret is being configured when a webhook is created
const client_secret = 'my little secret';
var requestBody = '';
req.on('readable', () => {
var read = req.read()
if(read != null) {
requestBody += read;
}
});
req.on('end', () => {
jsonBody = JSON.stringify(requestBody);
// do whatever you need with jsonBody, however use requestBody in the signature payload
signature = crypto.createHmac('sha512',client_secret).update(requestBody).digest('hex');
console.log('Signature:' + signature);
res.writeHead(200);
res.end(signature);
})
}
const server = http.createServer(requestListener);
server.listen(serverPort);
Argyle webhooks are currently delivered from two static IP addresses:
35.188.163.115
34.122.50.253
Verifying authenticity via these IPs is not recommended and should only be used as a fallback method because these addresses could change in the future.
Use case: keeping all activities on your system in sync
Here is how webhooks can help you to have all activity data downloaded on your own servers, and keep it in sync with the Argyle API:
- Subscribe to
activities.fully_synced
to get notified when the initial account sync of all historical data is finished. Whenever the webhook is invoked, query the activities from the API with the following query:/activities?from_start_date=available_from&account=account_id&to_start_date=available_to
whereaccount
is the account ID, andavailable_from
andavailable_to
are timestamps from the webhook payload. - Subscribe to
activities.added
to get notified when new activities are added after the initial sync. Argyle scans all accounts periodically for new activities and other changes in data. Use the same API call, but withadded_from
andadded_to
timestamps from the webhook payload. - Subscribe to
activities.updated
to get notified when existing activities change. An example of this would be when additional information about a completed activity is passed along at a later time (e.g. tips for a completed delivery or ride). The webhook payload provides the date range that was updated (updated_from
andupdated_to
) along with an array of activity IDs that were updated (updated_activities
) to make syncing of the data more convenient. - Subscribe to
activities.removed
to get notified when activities are removed by a data provider. This webhook is an indication to make sure that the activities are removed from your database to avoid duplicate data for a specific account. The webhook payload provides the date range when activities were removed (removed_from
andremoved_to
), the number of activities that were removed (removed_count
), along with an array of activity IDs that were removed (removed_activities
).
Updated 7 months ago