Skip to main content
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: 
{
    "events": ["webhook.1", "webhook.2", "..."],
    "name": "name-for-the-webhook-subscription",
    "url": "https://your-webhook-backend.com",
    "secret": "optional-secret",            // Optional.
    "config": { "include_resource": true }  // Optional. Can only be applied to certain webhooks.
}
  • 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: 
{
    "event": "accounts.added",
    "name": "name-for-the-webhook-subscription",
    "data": {
        "account": "0187c66e-e7e5-811c-b006-2232f00f426a",
        "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69"
    }
}
…would have the following signature: 
"X-Argyle-Signature": "1b158d292b0514f437481f0f1fbb4193ced2ab45b47a6c1255c66e1b8e614d482fd437f23590e8b1d0dd363228ba1ea3261ee0727db132dc0e8d9873fb09c880"

​
Example validation

​
using Node:

const http = require('http');
const crypto = require('crypto');
const serverPort = 80
const requestListener = function (req, res) {
    const client_secret = 'my little secret';
    var requestBody = '';
    req.on('readable', () => {
        var read = req.read()
        if(read != null) {
        requestBody += read;
        }
    });
    req.on('end', () => {
        // Make sure to use the raw requestBody when validating the signature.
        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);

​
Webhook management

​
List all webhooks

Send a GET request to the /v2/webhooks API endpoint.
  • from_created_at — Filter for webhooks created on or after this timestamp (ISO 8601).
  • to_created_at — Filter for webhooks created on or before this timestamp (ISO 8601).
  • ordering — Use id to order the list results by webhook ID. Use created_at to order the list results by when the webhooks were created.
  • limit — Limit the number of results returned per page. Default: 10. Maximum: 200.
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.
{
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "205c027e-8a4d-4248-b395-d4f345dfd49f",
            "name": "name-for-the-webhook-subscription",
            "events": [
                "accounts.added"
            ],
            "config": {
                "include_resource": true
            },
            "secret": "optional-secret",
            "url": "https://your-webhook-backend.com",
            "created_at": "2024-08-30T13:58:53.683338Z",
            "updated_at": "2024-10-07T15:20:49.926525Z",
            "last_sent_at": "2024-10-07T15:19:49.412642Z"
        }
    ]
}

​
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.

​
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