🧠 Deep Dive

Receiving outputs generated by Ason

Integration Ason into your platform usually means getting access to the outputs that Ason generates. This can mean automatically importing positions from the accounting document or providing a platform-native way for your clients to access the document from the payroll process.
Ason makes this easy by allowing you to subscribe to webhook events for the closure / finalization of the payrun period.
The event for the closure will be fired shortly after closing the period. Documents associated with the closure are AccountingDocument, Payslip, CumulativeJournal and PaymentFile.
The finalization of the period can take longer. Ason handles the submission to regulatory bodies in each country and will fire the finalization of the period when the process is complete. Depending on the country different documents will be available from this process.

Webhook setup

First, lets set up a webhook to get notified about these events.

Code
curl -X 'POST' \
'https://sandbox-api.asonpayroll.com/api/tenants/<TENANTID>/webhooks \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "payloadUrl": "https://yourplatform.com/ingest/ason",
  "events": [
    {
      "$type": "PayrunPeriodClosed"
    },
    {
      "$type": "PayrunPeriodFinalized"
    }
  ],
  "secret": "<SECRET>",
  "payloadMetadata": {
    "platformCompanyId": "<ID>"
  }
}'

• payloadUrl: The endpoint Ason will try to send a HTTP POST request with the webhook payload to.
• events: List of events to subscribe to.
• secret: A secret. More on that below.
• payloadMetadata: This collection will be send with each payload. Useful for adding mapping information.

To create webhooks you need to be an admin of the tenant/organisation.

Payload

All webhook payloads contain at least these fields:

• $type: discrimator for the type of payload.
• correlationId: The correlationId of the event. Stable between redeliveries.
• timestamp: Timestamp of when Ason generated the payload.
• metadata: Metadata you provided when creating the webhook.

Additionally these fields will present for the PayrunPeriodClosed/Finalized events:

• $type = WebhookPayloadPayrunPeriodClosed / WebhookPayloadPayrunPeriodFinalized
• payrollId: The ason id of the payroll.
• payrunPeriodId: The ason id of the payrun period.
• periodStart: Start date of the payrun period.
• periodEnd: End date of the payrun period.

Security

Your endpoint receiving the Ason webhook needs to verify that the incoming request is originating from Ason.
Requests from Ason will contain the Header X-Ason-Signature: sha256=<signature>.
Ason generates signatures using a hash-based message authentication code (HMAC) with SHA-256.
To verify the signature take the secret you provided when creating the webhook as the key and use the request body as message.

Retrieval

The webhook events are thin events thus they do not contain any documents.
Use the ExecuteQuery endpoint to get a summary of a payrun period.

Code
curl -X 'POST' \
'https://sandbox-api.asonpayroll.com/api/tenants/<TENANTID>/query \
-H 'accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
  "$type": "PayrunPeriodSummaryRequest",
  "payrunPeriodId": <PAYRUNPERIODID>
}'

The response will have this schema:

Code
{
  "status": "Open" | "Closed" | "Finalized",
  "billedEmployeeCount": number,
  "documents": Array<{
    "id": uuid,
    "name": string,
    "contentType": string,
    "url": string,
    "type":
      "AccountingDocument" |
      "CumulativeJournal" |
      "Payslip" |
      "PaymentFile" |
      "Switzerland_SalaryCertificate" |
      "Switzerland_OASI" |
      "Switzerland_FAF" |
      "Switzerland_AccidentInsurance" |
      "Switzerland_SupplementaryAccidentInsurance" |
      "Switzerland_SicknessDailyAllowance" |
      "Switzerland_WithholdingTax",
    "employeeId": uuid | null, // if null this is a payroll wide document,
    "employeeAttributes": Record<string, any>
  }>
}

You can use the url of the document object to download the associated document with a GET request. This is not a temporary download link, as such the Authorization header is still required.

Testing

In the sandbox environment the finalization of the period is faked. Shortly after closing the period a finalized event will be sent with a document for each listed category.