Webhooks

Subscribe to payroll updates and get notified instantly.

Overview#

Webhooks provide real-time notifications to your system when events take place, or new data is added, updated, or deleted.

Example scenarios:

  • A new payroll connection is attempted.
  • Data retrieval from a recently connected account has completed.
  • New data is available for a connected account.
  • A deposit switch is successful.

Webhooks are not specific to individual users or accounts.

For example, if you are subscribed to the identities.added webhook, new identity information added to any account of any user will cause the webhook to be delivered.

Additional resources:

Webhooks Reference — Complete list of available webhooks and their descriptions.
Console Webhooks — Learn more about subscribing to and managing webhooks via Console.

Webhooks are not designed to be a primary source of analytics information. For detailed metrics on step-by-step conversion success rates, visit the Conversion area of Console's Dashboard or contact your customer success manager.

Subscribing to webhooks#

Send a POST request to the /v2/webhooks API endpoint. In the request body, include a JSON object in the format:

1{
2    "events": ["webhook.1", "webhook.2", "..."],
3    "name": "name-for-the-webhook-subscription",
4    "url": "https://your-webhook-backend.com",
5    "secret": "optional-secret",            // Optional.
6    "config": { "include_resource": true }  // Optional. Can only be applied to certain webhooks.
7}
  • events — List all webhooks to include in the subscription.

    To subscribe to all webhooks at once, use "*".

    • This method will not subscribe you to any Items webhooks.
    • This method does not allow you to specify the number of days synced for the paystubs.partially_synced and gigs.partially_synced webhooks.
    • For webhooks that have an optional config parameter (used to return an account object in the webhook's payload), you must subscribe to these webhooks individually to receive this optional account object.
  • name — Your name for the set of webhooks in the subscription.

  • url — Where you want to receive webhook delivery. This can be either a backend URL that you manage, or a URL provided by a webhook management service.

    Argyle delivers webhooks from four static IP addresses:

    • 34.27.251.226
    • 34.122.50.253
    • 35.188.163.115
    • 35.226.53.251
  • secret — (Optional) A secret word or phrase that can be used to authenticate webhooks you receive. See below for more information on verifying webhooks.

  • config — (Optional) Some webhooks will return a payload when include_resource is set to true.

Verifying webhooks#

When you receive webhooks that were subscribed to using an optional secret, an Argyle signature will be included in the header. The secret can be any string of characters.

Steps#

To verify the authenticity of a webhook:

  1. Use HMAC-SHA512 to directly encode the received payload body without any added adjustments. Use the webhook's secret as the secret key for encoding.
  2. The webhook is genuine if the encoded payload matches the Argyle signature in the header.

Example signature#

If your secret was my little secret

...the following body:

1{"name": "Account added", "event": "accounts.added"}

...would have the following signature:

1"X-Argyle-Signature": "13b68c651cdf714d8d00e88d3c9997d2ea2cb6ffcc57ba2d9164af5898169124e75505f354ded4350c96b03b2cddf01cbe71bc26cb2dc656a69ef670bcda0f86"

Example validation#

using Node:

1const http = require('http');
2const crypto = require('crypto');
3
4const serverPort = 80
5const requestListener = function (req, res) {
6    const client_secret = 'my little secret';
7    var requestBody = '';
8    req.on('readable', () => {
9        var read = req.read()
10        if(read != null) {
11        requestBody += read;
12        }
13    });
14    req.on('end', () => {
15        // Make sure to use the raw requestBody when validating the signature.
16        signature = crypto.createHmac('sha512',client_secret).update(requestBody).digest('hex');
17        console.log('Signature:' + signature);
18        res.writeHead(200);
19        res.end(signature);
20    })
21}
22const server = http.createServer(requestListener);
23server.listen(serverPort);

Webhook management#

List all webhooks#

Send a GET request to the /v2/webhooks API endpoint.

Retrieve a webhook#

Send a GET request to the /v2/webhooks/{id} API endpoint, and replace the {id} with the webhook's ID.

Delete a webhook#

Send a DELETE request to the /v2/webhooks/{id} API endpoint, and replace the {id} with the webhook's ID.

Webhook ID's are returned in the API response when subscribing to webhooks, or can be found by listing webhooks.


API Reference

Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com