>  Switch To Link 5 and API v2 Documentation

Payouts Webhooks

Learn about payouts webhooks.

There are two types of payout webhook events:

  • Events that trigger only during the initial scan when a new account is connected: payouts.fully_synced and payouts.partially_synced. They will trigger once per invocation for each added account.
  • Events that trigger later on, when new payouts are added in the future: payouts.added and payouts.updated. They will only trigger during a periodic scan for accounts that are already connected and have been fully synced, and only after the payouts.fully_synced event has been triggered.

A typical account can contain thousands of payouts and payouts.fully_synced will only fire after all of the payouts are scanned, which in some cases might take hours. Therefore, payouts.partially_synced can be used if only a partial range of the payouts is needed. For example, a history of the last 30 days instead of a complete history of payouts. This will reduce the sync time to minutes or, in some cases, seconds.

For more information about initial and periodic scans, with specific examples for using payout webhook events, please check the Data Retrieval Guide.

#Fully synced

post/v1/webhooks

Implement the payouts.fully_synced webhook to know when all payouts are fully scanned.

  • payouts.fully_synced triggers when all payouts are fully scanned. Scanning starts from the most recent payouts and finishes with the oldest ones.

This webhook only triggers when the initial scan finishes. It is not invoked during periodic scanning.

Request body
  • #
    eventsarray of strings
    required

    payouts.fully_synced

  • #
    namestring
    required

    Your name for the webhook subscription.

  • #
    urlstring
    required

    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.

  • #
    secretstring
    optional

    Optional secret used to verify webhooks.

Webhook message
  • #
    eventstring

    payouts.fully_synced

  • #
    namestring

    Name used for the webhook subscription.

  • #
    dataobject

  • #
    accountstring (uuid)

    ID of the account.

  • #
    userstring (uuid)

    ID of the user.

  • #
    available_fromstring (timestamp)

    The date of the oldest available payout.

    The available_from timestamp will precede the available_to timestamp.

  • #
    available_tostring (timestamp)

    The date of the most recent available payout.

  • #
    available_countinteger

    The total number of payouts associated with the account at the moment the webhook call is made.

Example Subscription
1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["payouts.fully_synced"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret"
10     }'
Example Webhook
1{
2  "event": "payouts.fully_synced",
3  "name": "All historical data synced",
4  "data": {
5    "account": "12db5af4-fd5f-4d1f-bd98-0360df770aa8",
6    "user": "abdb5af4-fd5f-4d1f-bd10-0360df77012c",
7    "available_from": "2019-03-07T20:12:09Z",
8    "available_to": "2019-09-23T23:57:31Z",
9    "available_count": 432
10  }
11}

#Partially synced

post/v1/webhooks

Implement the payouts.partially_synced webhook to know when 30 days of historical payouts have been scanned.

  • By default, the payouts.partially_synced webhook triggers when 30 days of historical payouts have been successfully scanned (starting from the most recent payouts).
  • The number of days scanned is a configurable parameter. You can subscribe this webhook to multiple times with different day ranges.
  • It triggers only on the initial scan, and does not trigger during a periodic scan. If an account has zero or a small number of payouts, the initial scan may return all historical data and only fire the payouts.fully_synced webhook.
Request body
  • #
    eventsarray of strings
    required

    payouts.partially_synced

  • #
    namestring
    required

    Your name for the webhook subscription.

  • #
    urlstring
    required

    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.

  • #
    secretstring
    optional

    Optional secret used to verify webhooks.

  • #
    configobject
    optional

    "days_synced": <Integer> dictates the number of days to be scanned. The default value is 30.

Webhook message
  • #
    eventstring

    payouts.partially_synced

  • #
    namestring

    Name used for the webhook subscription.

  • #
    dataobject

  • #
    accountstring (uuid)

    ID of the account.

  • #
    userstring (uuid)

    ID of the user.

  • #
    days_syncedinteger

    Number of historical days synced.

  • #
    available_fromstring (timestamp)

    Payouts synced on or after this date. Timestamps follow the ISO 8601 standard.

  • #
    available_tostring (timestamp)

    Payouts synced on or before this date. Timestamps follow the ISO 8601 standard.

  • #
    available_countinteger

    Total number of payouts synced.

Example Subscription
1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["payouts.partially_synced"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret",
10        "config": { "days_synced": 7 }
11     }'
Example Webhook
1{
2  "event": "payouts.partially_synced",
3  "name": "7 days synced",
4  "data": {
5    "account": "12db5af4-fd5f-4d1f-bd98-0360df770aa8",
6    "user": "abdb5af4-fd5f-4d1f-bd10-0360df77012c",
7    "days_synced": 7,
8    "available_from": "2019-06-07T20:12:09Z",
9    "available_to": "2019-06-14T20:12:09Z",
10    "available_count": 324
11  }
12}

#Added

post/v1/webhooks

Implement the payouts.added webhook to know when a payout object is added.

  • A new payout object is added after a periodic scan when a user receives a new paystub. If the scan detects more than one paystub, then the added_count value in the payload reflects this.
Request body
  • #
    eventsarray of strings
    required

    payouts.added

  • #
    namestring
    required

    Your name for the webhook subscription.

  • #
    urlstring
    required

    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.

  • #
    secretstring
    optional

    Optional secret used to verify webhooks.

Webhook message
  • #
    eventstring

    payouts.added

  • #
    namestring

    Name used for the webhook subscription.

  • #
    dataobject

  • #
    accountstring (uuid)

    ID of the account.

  • #
    userstring (uuid)

    ID of the user.

  • #
    added_fromstring (timestamp)

    Represents the start of the time period the payouts were added for. The added_from timestamp will precede the added_to timestamp.

    To get the added payouts, you can query the payouts endpoint by specifying the added_from, added_to range in the request parameters.

  • #
    added_tostring (timestamp)

    Represents the end of the time period the payouts are added for.

  • #
    added_countinteger

    The number of payouts added to the account.

  • #
    available_fromstring (timestamp)

    Represents the start of the time period the payouts are available for.

    The available_from timestamp will precede the available_to timestamp.

  • #
    available_tostring (timestamp)

    Represents the end of the time period the payouts are available for.

  • #
    available_countinteger

    The total number of payouts associated with the account at the moment the webhook call is made.

Example Subscription
1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["payouts.added"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret"
10     }'
Example Webhook
1{
2  "event": "payouts.added",
3  "name": "Payouts added",
4  "data": {
5    "account": "12db5af4-fd5f-4d1f-bd98-0360df770aa8",
6    "user": "abdb5af4-fd5f-4d1f-bd10-0360df77012c",
7    "added_from": "2019-08-07T20:12:09Z",
8    "added_to": "2019-09-23T23:57:31Z",
9    "added_count": 10,
10    "available_from": "2019-03-07T20:12:09Z",
11    "available_to": "2019-09-23T23:57:31Z",
12    "available_count": 456
13  }
14}

#Updated

post/v1/webhooks

Implement the payouts.updated webhook to know when a payout object is updated.

  • Payout objects are updated when a periodic scan detects changes to an existing payout — for example, the status of a payout execution changes from scheduled to completed.
Request body
  • #
    eventsarray of strings
    required

    payouts.updated

  • #
    namestring
    required

    Your name for the webhook subscription.

  • #
    urlstring
    required

    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.

  • #
    secretstring
    optional

    Optional secret used to verify webhooks.

Webhook message
  • #
    eventstring

    payouts.updated

  • #
    namestring

    Name used for the webhook subscription.

  • #
    dataobject

  • #
    accountstring (uuid)

    ID of the account.

  • #
    userstring (uuid)

    ID of the user.

  • #
    updated_fromstring (timestamp)

    Represents the start of the time period the payouts were updated in.

    The updated_from timestamp will precede the updated_to timestamp.

  • #
    updated_tostring (timestamp)

    Represents the end of the time period the payouts were updated in.

  • #
    updated_countinteger

    The number of payouts that were updated.

  • #
    updated_payoutsarray of (uuid) strings

    ID's of the updated payouts.

  • #
    available_fromstring (timestamp)

    Represents the start of the time period the payouts are available for.

    The available_from timestamp will precede the available_to timestamp.

  • #
    available_tostring (timestamp)

    Represents the end of the time period the payouts are available for.

  • #
    available_countinteger

    The total number of payouts associated with the account at the moment the webhook call is made.

Example Subscription
1curl --request POST \
2     --url https://api.argyle.com/v1/webhooks \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "events": ["payouts.updated"],
7        "name": "name-for-the-webhook-subscription",
8        "url": "https://your-webhook-backend.com",
9        "secret": "optional-secret"
10     }'
Example Webhook
1{
2  "event": "payouts.updated",
3  "name": "Payouts updated",
4  "data": {
5    "account": "12db5af4-fd5f-4d1f-bd98-0360df770aa8",
6    "user": "abdb5af4-fd5f-4d1f-bd10-0360df77012c",
7    "updated_from": "2019-09-10T10:00:00Z",
8    "updated_to": "2019-09-12T12:00:00Z",
9    "updated_count": 2,
10    "updated_payouts": [
11      "d667a477-e252-4f8a-9518-92a51b235187",
12      "27f3cde1-1ca0-4b5a-940d-337fd33f97b5"
13    ],
14    "available_from": "2019-03-07T20:12:09Z",
15    "available_to": "2019-09-23T23:57:31Z",
16    "available_count": 456
17  }
18}
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com