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.

Additional resources:

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

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 webhook body:

1{
2    "event": "accounts.added",
3    "name": "name-for-the-webhook-subscription",
4    "data": {
5        "account": "0187c66e-e7e5-811c-b006-2232f00f426a",
6        "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"
7    }
8}

...would have the following signature:

1"X-Argyle-Signature": "1b158d292b0514f437481f0f1fbb4193ced2ab45b47a6c1255c66e1b8e614d482fd437f23590e8b1d0dd363228ba1ea3261ee0727db132dc0e8d9873fb09c880"

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.

When you list all webhooks, the last time a particular webhook was sent by Argyle is returned in a last_sent_at field. This field can be used for troubleshooting purposes to determine if a webhook was either not sent by Argyle, or sent by Argyle but not received by your webhook system.

1{
2    "next": null,
3    "previous": null,
4    "results": [
5        {
6            "id": "205c027e-8a4d-4248-b395-d4f345dfd49f",
7            "name": "name-for-the-webhook-subscription",
8            "events": [
9                "accounts.added"
10            ],
11            "config": {
12                "include_resource": true
13            },
14            "secret": "optional-secret",
15            "url": "https://your-webhook-backend.com",
16            "created_at": "2024-08-30T13:58:53.683338Z",
17            "updated_at": "2024-10-07T15:20:49.926525Z",
18            "last_sent_at": "2024-10-07T15:19:49.412642Z"
19        }
20    ]
21}

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 retry policy#

Webhooks have a 10 second timeout. If successful receipt of a webhook (200 response code) does not occur within the timeout window, webhooks will be resent once after 30 seconds for the following response codes: 429, 500, 502, 503, 504. Argyle does not log the body of sent webhooks.

API Reference