EmployerLink Webhook Reference

Webhooks are a useful way to receive automated updates via HTTP and send timely notifications to your user as a transaction progresses. On this page you'll find details about the contents of our webhook event requests. For in-depth guides on how to set up, test, and secure webhooks, check out the Webhooks Guides.

Cloud Events

All Atomic webhook events conform to the CloudEvents.io protocol using the binary content mode. This table shows the CloudEvents headers along with sample values to illustrate what is sent with each event.

Header	Value
`ce-specversion`	`1.0`
`ce-source`	`com.atomicfi`
`ce-type`	`com.atomicfi.[event-type]`
`ce-time`	`2022-04-13T21:36:42.985Z`
`ce-id`	`257426ab237ac6786a23d52`

Event object

Webhook events will include a set of standard properties in the request body, as described below.

eventTypestring: This indicates what type of event is being sent. The eventType attribute is the primary field for routing webhooks as they are received by your webhook endpoint. All available options are detailed on this page.
eventTimestring: The date and time of the event creation in ISO 8601 format at UTC+0.
userobject: Object containing _id and identifier where identifier is the identifier for this user in your system (used when creating the AccessToken) and the _id is an Atomic assigned id for the user.
dataobject: The payload of the event. This object will change depending on the eventType. Corresponding attributes are detailed for each webhook below.

Sample Request Body

{
  "eventType": "sample-event-type",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "user": {
    "_id": "5c17c632e1d8ca3b08b2586f",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "data": {
    "hello": "world"
  }
}

Tasks

Each discrete payroll operation, such as a verification of income or a direct deposit switch, will instantiate what is referred to as Task in our system.

When a Task resolves, you will receive the task-status-updated webhook. If the Task was successful, the status attribute will be set to completed. If there was an issue with the Task processing, status will be failed along with a reason attribute containing the reason for the failure. The failure reasons are enumerated below.

Task event object

In addition to the standard event properties, all Task events will also include the following:

publicTokenstring: Public Access Token used when initializing the Transact SDK.
productenum: The product relevant to the executed task. Options are:
enroll
user.connectedboolean: Indicates whether or not the user was present to view a confirmation of the task's final outcome.
companyobject: The payroll provider or employer which this Task interacts with. Returned as an object containing _id, name, and branding.
metadataobject: The metadata provided by your system when the task was initialized.
taskstring: The ID of the Task; useful for debugging purposes.
taskWorkflowstring: The ID of the Task Workflow; useful for debugging purposes. A Task Workflow is a logical container in our backend for orchestrating Tasks.
dataobject: Payload object containing a reason attribute if a Task failed (see Task failures below), previousStatus, status, distributionType (if applicable), distributionAmount (if applicable), and outputs.

Sample

{
  "eventType": "task-status-updated",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "publicToken": "PUBLIC_TOKEN",
  "product": "deposit",
  "user": {
    "_id": "5d8d3fecbf637ef3b11a877a",
    "identifier": "YOUR_INTERNAL_IDENTIFIER",
    "connected": true
  },
  "company": {
    "_id": "5d9a3fecbf637ef3b11ab442",
    "name": "Home Depot",
    "branding": {
      "logo": {
        "url": "https://atomicfi-public-production.s3.amazonaws.com/979115f4-34a0-44f5-901e-753a33337444_atomic-logo-dark.png"
      }
    }
  },
  "metadata": {
    "orderId": "123"
  },
  "task": "5e30afde097146a8fc3d5cec",
  "taskWorkflow": "5e30afde097146a8fc3d5ceb",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "distributionType": "fixed",
    "distributionAmount": 25
  }
}

JSON Schema

{
  "type": "object",
  "title": "Atomic Webhook Event",
  "description": "Structure of a webhook event sent by Atomic Financial",
  "properties": {
    "eventType": {
      "type": "string",
      "description": "Indicates the type of the event being sent."
    },
    "eventTime": {
      "type": "string",
      "description": "The date and time of the event creation in ISO 8601 format."
    },
    "publicToken": {
      "type": "string",
      "description": "Public Access Token used when initializing the Transact SDK."
    },
    "product": {
      "type": "enum",
      "description": "The product relevant to the executed Task. Options are deposit, verify, earn, paylink, or tax."
    },
    "user": {
      "type": "object",
      "description": "Object containing _id, identifier, and connected where identifier is your internal unique identifier and connected indicates whether or not the user was present to view a confirmation of the Task's final outcome.",
      "properties": {
        "_id": {
          "type": "string",
          "description": "Identifier for the user created by Atomic."
        },
        "identifier": {
          "type": "string",
          "description": "Your unique identifier for the user."
        },
        "connected": {
          "type": "boolean",
          "description": "Indicates whether or not the user was present to view a confirmation of the Task's final outcome."
        }
      }
    },
    "company": {
      "type": "object",
      "description": "Object containing _id, name, and branding for the payroll company.",
      "properties": {
        "_id": {
          "type": "string",
          "description": "Identifier for the company"
        },
        "name": {
          "type": "string",
          "description": "Company name"
        },
        "branding": {
          "type": "object",
          "description": "Metadata for the company's styling and branding.",
          "properties": {
            "logo": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "The metadata provided when the Task was initialized."
    },
    "task": {
      "type": "string",
      "description": "The ID of the Task."
    },
    "taskWorkflow": {
      "type": "string",
      "description": "The ID of the Task workflow."
    },
    "data": {
      "type": "object",
      "description": "Payload object containing reason (if a failed Task), previousStatus, status, distributionType (if applicable), distributionAmount (if applicable), and outputs.",
      "properties": {
        "reason": {
          "type": "string",
          "description": "For Tasks that failed, the reason why the Task failed. These are enumerated on in the Webhook reference page."
        },
        "previousStatus": {
          "type": "enum",
          "description": "Previous status of the Task. Options are queued or processing"
        },
        "status": {
          "type": "enum",
          "description": "Current status of the Task. Options are processing, failed, or completed."
        },
        "distributionType": {
          "type": "enum",
          "description": "For Deposit Tasks, the type of the distribution. Options are `total`, `fixed`, or `percent`. `total` indicates 100% of the paycheck is allocated for deposit, `fixed` is the specified amount, and `percent` is the specified percentage of the paycheck."
        },
        "distributionAmount": {
          "type": "number",
          "description": "For deposit Tasks, the amount of the distribution. When the distributionType is fixed, this indicates the specific amount of the payroll allocation. For total and percent distributionTypes, this number indicates the percentage of the paycheck allocated; total being 100 and percent indicating the percentage specified by the user."
        },
        "outputs": {
          "type": "object",
          "description": "For Verify Tasks, the data retrieved from the payroll system."
        }
      }
    }
  }
}

Task status updated

When a task-status-updated event is emitted, this indicates that the state of the Task has changed. For example, the Task has gone from processing to finished or completed. If the status is a final status, either finished or completed, no further updates will occur, though a task status patched event may be emitted.

statusenum: The current state of the Task. Options are processing, failed and completed. Failed and completed are final states indicating either a successful or unsuccessful Task.
previousStatusenum: The state which the Task was in before the current status. Options are queued and processing.
reasonenum: Optional. For Tasks that failed, this is the reason why the Task failed. These are enumerated in the Task Failures section.
outputsobject: Optional. For Verify Tasks, this object will contain the data retrieved from the payroll system. For more information see the Task outputs section.
distributionTypeenum: Optional. For Deposit Tasks, the type of the distribution. Options are total, fixed, or percent. total indicates 100% of the paycheck is allocated for deposit, fixed is the specified amount, and percent is the specified percentage of the paycheck.
distributionAmountenum: Optional. For deposit Tasks, the amount of the distribution. When the distributionType is fixed, this indicates the specific amount of the payroll allocation in dollars. For percent distributionTypes, this number indicates the percentage of the paycheck allocated by the user. If the payroll allocation was total, this attribute will be omitted.

Sample task-status-updated event

{
  "eventType": "task-status-updated",
  "eventTime": "2021-01-13T19:43:26.097Z",
  "product": "deposit",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "distributionType": "fixed",
    "distributionAmount": 25
  }
  
  // additional Task event attributes removed for simplicity
}

Task authentication status updated

When eventType is task-authentication-status-updated, the authentication status of a Task was changed. Possible authenticated statuses include:

authenticatedboolean: Indicates whether or not the Task has successfully authenticated against the payroll system.

Sample task authentication status updated event

{
  "eventType": "task-authentication-status-updated",
  "eventTime": "2021-01-13T19:43:26.097Z",
  "product": "deposit",
  "data": {
    "authenticated": true
  }
  
  // additional Task event attributes removed for simplicity
}

Task status patched

When eventType is task-status-patched, the final status of a Task was updated. Cases where this may occur are rare and are generally associated with an audit or bug fix within our system. Possible statuses include:

statusenum: The current state of the Task. Options are processing, failed and completed. Failed and completed are final states indicating either a successful or unsuccessful Task.
previousStatusenum: The state which the Task was in before the current status. Options are queued and processing.
distributionTypeenum: Optional. For Deposit Tasks, the type of the distribution. Options are total, fixed, or percent. total indicates 100% of the paycheck is allocated for deposit, fixed is the specified amount, and percent is the specified percentage of the paycheck.
distributionAmountenum: Optional. For deposit Tasks, the amount of the distribution. When the distributionType is fixed, this indicates the specific amount of the payroll allocation in dollars. For percent distributionTypes, this number indicates the percentage of the paycheck allocated by the user. If the payroll allocation was total, this attribute will be omitted.

Sample task status patched event

{
  "eventType": "task-status-patched",
  "eventTime": "2021-01-13T19:43:26.097Z",
  "product": "deposit",
  "data": {
    "previousStatus": "failed",
    "status": "completed",
    "distributionType": "fixed",
    "distributionAmount": 25
  }  

  // additional Task event attributes removed for simplicity
}

Task outputs

Employment data is contained within an data.outputs object. The data delivered to you will depend on the Task's product and other considerations listed below. For your convenience, this data may include both raw and derived fields.

Verify

If you are using verify, you'll receive data as described in our Employment Data Reference. The data retrieved will depend on your data scoping configuration and what we are able to access within the payroll system.

Sample response for verify

{
  // additional Task event attributes removed for simplicity
  "eventType": "task-status-updated",
  "eventTime": "2021-05-24T18:27:09.610Z",
  "product": "verify",
  "data": {
    "previousStatus": "processing",
    "status": "completed",
    "authenticated": true,
    "outputs": {
      "income": 45000,
      "incomeType": "yearly",
      "annualIncome": 45000,
      "hourlyIncome": 21.63,
      "netHourlyRate": 18.44,
      "employeeType": "fulltime",
      "employmentStatus": "active",
      "jobTitle": "Product Manager",
      "startDate": "2017-04-19T12:00:00.000Z",
      "minimumMonthsOfEmployment": 58,
      "weeklyHours": 40,
      "payCycle": "semimontly",
      "nextExpectedPayDate": "2020-06-30T12:00:00.000Z",
      "currentPayPeriodStart": "2020-06-13T12:00:00.000Z",
      "currentPayPeriodEnd": "2020-06-27T12:00:00.000Z",
      "unpaidHoursInPayPeriod": 24,
      "firstName": "Jane",
      "lastName": "Appleseed",
      "dateOfBirth": "1984-04-12T19:00:00.000Z",
      "email": "jappleseed@example.org",
      "phone": "8015551111",
      "ssn": "111223333",
      "address": "123 Street St.",
      "city": "Provo",
      "state": "UT",
      "postalCode": "84606",
      "statements": [
        {
          "date": "2020-06-15T12:00:00.000Z",
          "payPeriodStartDate": "2020-05-27T12:00:00.000Z",
          "payPeriodEndDate": "2020-06-12T12:00:00.000Z",
          "grossAmount": 1875,
          "ytdGrossAmount": 10000,
          "netAmount": 1620,
          "ytdNetAmount": 8000,
          "hours": 96,
          "deductions": [
            {
              "category": "taxes",
              "label": "Federal Income Tax",
              "rawLabel": "Federal Income Tax",
              "amount": 200,
              "ytdAmount": 2000
            },
            {
              "category": "taxes",
              "label": "State Income Tax",
              "rawLabel": "Utah State Tax",
              "amount": 50,
              "ytdAmount": 500
            },
            {
              "category": "other",
              "label": "Abc corp dd",
              "rawLabel": "Abc corp dd",
              "amount": 5,
              "ytdAmount": 50
            }
          ],
          "earnings": [
            {
              "category": "benefit",
              "rawLabel": "Social Security (Disability)",
              "amount": 1000
            },
            {
              "category": "bonus",
              "rawLabel": "Quarterly Bonus",
              "amount": 2000,
              "ytdAmount": 6000
            },
            {
              "category": "overtime",
              "rawLabel": "Overtime Pay",
              "amount": 100,
              "ytdAmount": 1000,
              "hours": 10,
              "rate": 15
            },
            {
              "category": "reimbursement",
              "rawLabel": "Gas Card",
              "amount": 25.47,
              "ytdAmount": 85.74
            }
          ],
          "paystub": {
            "_id": "60abeff50836730008616fad",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        },
        {
          "date": "2020-05-31T12:00:00.000Z",
          "payPeriodStartDate": "2020-05-11T12:00:00.000Z",
          "payPeriodEndDate": "2020-05-26T12:00:00.000Z",
          "grossAmount": 1875,
          "hours": 88,
          "deductions": [
            {
              "category": "taxes",
              "label": "Federal Income Tax",
              "rawLabel": "Federal Income Tax",
              "amount": 200
            },
            {
              "category": "taxes",
              "label": "State Income Tax",
              "rawLabel": "Utah State Tax",
              "amount": 50
            },
            {
              "category": "other",
              "label": "Abc corp dd",
              "rawLabel": "Abc corp dd",
              "amount": 5
            }
          ],
          "paystub": {
            "_id": "60abeff50836730008616fae",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          }
        }
      ],
      "accounts": [
        {
          "routingNumber": "123123123",
          "accountNumber": "1122330000",
          "type": "checking",
          "bankName": "Molecular Bank",
          "distributionType": "percent",
          "distributionAmount": 80
        },
        {
          "routingNumber": "456456456",
          "accountNumber": "XXXX1111",
          "type": "savings",
          "bankName": "Molecular Bank",
          "distributionType": "percent",
          "distributionAmount": 20
        }
      ],
      "w2s": [
        {
          "year": "2020-01-01T00:00:00.000Z",
          "totalWages": 50000,
          "form": {
            "_id": "60abeff60836730008616faf",
            "url": "[ATOMIC-GENERATED-PRESIGNED-S3-URL]"
          },
          "parsedData": {
            "taxYear": 2022,
            "employeeTin": "XXX-XX-1234",
            "employerTin": "12-3456789",
            "employerNameAddress": {
              "name1": "Tax Form Issuer, Inc",
              "line1": "12021 Sunset Valley Dr",
              "city": "Preston",
              "state": "VA",
              "postalCode": "20191"
            },
            "controlNumber": "012547 WY/OA7",
            "employeeName": {
              "first": "Kris",
              "last": "Public"
            },
            "employeeAddress": {
              "line1": "1 Main St",
              "city": "Melrose",
              "state": "NY",
              "postalCode": "12121"
            },
            "wages": 44416.74,
            "federalTaxWithheld": 6907.16,
            "socialSecurityWages": 47162.92,
            "socialSecurityTaxWithheld": 2924.1,
            "medicareWages": 47162.92,
            "medicareTaxWithheld": 683.86,
            "socialSecurityTips": 134.25,
            "allocatedTips": 149.75,
            "dependentCareBenefit": 543.25,
            "nonQualifiedPlan": 354.23,
            "codes": [
              {
                "code": "C",
                "amount": 301.5
              },
              {
                "code": "D",
                "amount": 2746.18
              },
              {
                "code": "DD",
                "amount": 4781.88
              }
            ],
            "other": [
              {
                "description": "Housing",
                "amount": 6500
              },
              {
                "code": "Union Dues",
                "amount": 1500
              }
            ],
            "stateTaxWithholding": [
              {
                "stateTaxWithheld": 1726.78,
                "state": "OH",
                "stateTaxId": "OH 036-133505158F-01",
                "stateIncome": 44416.74
              }
            ],
            "localTaxWithholding": [
              {
                "localTaxWithheld": 427.62,
                "localityName": "Kirtland",
                "state": "OH",
                "localIncome": 44416.74
              }
            ]
          }
        }
      ],
      "timesheets": [
        {
          "type": "unpaid",
          "duration": 420,
          "date": "2020-05-31T12:00:00.000Z"
        }
      ]
    }
  }
}

Task failures

Tasks may fail for many different reasons. If a task fails, we will include a reason property with the event's data object. Possible values include:

account-lockout: The account is locked out, most likely the end user has had too many failed attempts.
account-setup-incomplete: The user's account in the payroll system is not fully set up and will require additional information from the user.
account-unusable: The user's bank account is unusable for the selected product or use case.
bad-credentials: Either the username or password was incorrect. This is our most common fail reason.
connection-error: A network error occurred which caused the connection between our system and the payroll system to be lost.
distribution-not-supported: The payroll system did not support the type of distribution requested. For example, the user attempted to allocate a percentage of their paycheck, but is only eligible for fixed amounts and remainder/net balance.
enrolled-in-paycard: The user is enrolled in a paycard program instead of direct deposit via their bank.
expired: The user's password has expired and they must create a new one.
no-data-found: No verify data was found for the user.
product-not-supported: The payroll system did not allow the action to be taken. Many payroll systems allow HR to customize what is allowed in their system. Direct Deposit may be allowed by a payroll system, but may be disallowed by a specific employer. Therefore, when an employee of that company goes to set up Direct Deposit it is rejected, resulting in this error code.
routing-number-not-supported: The account did not support the routing number entered.
session-timeout: The user's session timed out.
system-unavailable: The system was unavailable. For example, the site is undergoing maintenance or it is outside the window of scheduled availability for the site.
transaction-pending: There is a deposit allocation already in progress and additional updates cannot be made at this time. For example, if an employer has an approval process in place, they may disallow modifications until the update has been processed.
unknown-failure: We encountered an unexpected error.
user-abandon: The user was asked an MFA question, but did not answer the question.
work-status-terminated: The task could not be completed because the user's employment has been terminated.

Example Task Failure Event

{
  "eventType": "task-status-updated",
  "eventTime": "2021-05-24T18:27:09.610Z",
  "product": "verify",
  "data": {
    "previousStatus": "processing",
    "status": "failed",
    "authenticated": false,
    "distributionType": "total",
    "reason": "system-unavailable"    
  }

  // additional Task event attributes removed for simplicity
}

Linked Account

A Linked Account is an account in which the end user has given Atomic permission to maintain a persistent connection with their payroll provider. Once the user has successfully authenticated with the payroll provider, a Linked Account is created in the Atomic system.

We are then able to run a weekly job which can access data or detect changes in the payroll system. This is how we establish Continuous Access to the payroll provider on behalf of the user.

Linked account connected

When eventType is linked-account-connected, the user has successfully authenticated with the payroll provider and the Linked Account has been created in the Atomic system.

In addition to the standard event properties, the data property includes the following:

linkedAccountLinked Account: The data for the Linked Account associated with the user's persistent connection. The _id is needed for your system to make calls to Atomic and use the connection again.

Sample linked-account-connected event

{
  "eventType": "linked-account-connected",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "user": {
    "_id": "5c17c632e1d8ca3b08b2586f",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "data": {
    "linkedAccount": {
      "_id": "5f7212103a40e91f95ba376d",
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      }
    }
  }
}

Linked account disconnected

When eventType is linked-account-disconnected, a user's Linked Account has been disconnected. Typically this occurs when a password expires or another change in the payroll system has severed the connection. This requires the user to go through Transact again and re-establish the connection.

In addition to the standard event properties, the data property includes the following:

linkedAccountLinked Account: The data for the Linked Account associated with the user's persistent connection. The _id is needed for your system to make calls to Atomic and use the connection again.

Sample linked-account-disconnected event

{
  "eventType": "linked-account-disconnected",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "user": {
    "_id": "5c17c632e1d8ca3b08b2586f",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "data": {
    "linkedAccount": {
      "_id": "5f7212103a40e91f95ba376d",
      "connector": {
        "_id": "5d77f95207085632a58945c3",
        "name": "ADP",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f6343c",
            "url": "https://cdn.atomicfi.com/adp-logo.svg"
          }
        }
      },
      "company": {
        "_id": "5d77f9e1070856f3828945c6",
        "name": "DoTerra",
        "branding": {
          "logo": {
            "_id": "5eb62781b4b83f0008f638cc",
            "url": "https://cdn.atomicfi.com/doterra-logo.svg"
          }
        }
      }
    }
  }
}

Employer

Employer updated

When eventType is employer-updated, an employer's data has updated and is ready to be retrieved.

In addition to the standard event properties, the data property includes the following:

uristring: The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employer endpoints.

Sample employer-updated event

{
  "eventType": "employer-updated",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "user": {
    "_id": "5c17c632e1d8ca3b08b2586f",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "data": {
    "uri": "https://api.atomicfi.com/employer/5d77f95207085632a58945c3"
  }
}

Employee

Employee updated

When eventType is employee-updated, one or more employee's data has updated and it ready to be retrieved.

In addition to the standard event properties, the data property includes the following:

uristring: The uri that can be used to retrieve the updated data. This uri will be a constructed https request against our employee endpoints.

Sample employee-updated event

{
  "eventType": "employee-updated",
  "eventTime": "2020-01-28T22:04:18.778Z",
  "user": {
    "_id": "5c17c632e1d8ca3b08b2586f",
    "identifier": "YOUR_UNIQUE_IDENTIFIER"
  },
  "data": {
    "uri": "https://api.atomicfi.com/employee?employeeId=5d77f95207085632a58945c3"
  }
}