Webhooks let your platform get notified the moment something happens in Ason - a case change was reported, a payout was created, a task changed, a payrun period closed or finalized - instead of polling for it.
Example: A platform reports hours and triggers a payout through a payrun period - here's exactly when Ason fires webhooks along the way. Click a step for details.
Once the period is closed (via API or UI), Ason generates payslips and the accounting document, then fires PayrunPeriodClosed. This is the first webhook your platform actually needs to act on - not tied to any single case change, but to the period as a whole.
Available events
| Event | Fires when |
|---|---|
CaseChangeAdded | A case change was reported (optionally filtered to specific caseNames) |
PayoutCreated | A payout was created |
PayoutCancellationRequested | A payout cancellation was requested |
TaskChanged | A task was created or updated |
PayrunPeriodClosed | A payrun period was closed |
PayrunPeriodFinalized | A payrun period's Swissdec submission completed - see Outputs |
You can subscribe to any combination of these on a single webhook.
Setting up a webhook
Code
payloadUrl: the endpoint Ason sends an HTTP POST request to for every matching event.events: the list of events to subscribe to, from the table above.secret: used to sign payloads - see "Security" below.payloadMetadata: an arbitrary object echoed back in every payload - useful for your own mapping information (e.g. your internal company id for this tenant).- Requires: an admin of the tenant to create a webhook
Payload
Every webhook payload contains at least these fields:
$type: which event this is (WebhookPayloadCaseChangeAdded,WebhookPayloadPayoutCreated,WebhookPayloadPayrunPeriodClosed,WebhookPayloadTaskChanged, ...).tenantId: the id of the tenant the event belongs to.correlationId: stable between redeliveries of the same event.timestamp: when Ason generated the payload (UTC).metadata: whatever you set aspayloadMetadatawhen creating the webhook.
Additional fields depend on the event:
$type | Additional fields |
|---|---|
WebhookPayloadCaseChangeAdded | payrollId, caseChangeId, employeeId (null for a company case), caseName |
WebhookPayloadPayoutCreated | payrollId, payrunPeriodId, payoutId |
WebhookPayloadTaskChanged | payrollId, taskId |
WebhookPayloadPayrunPeriodClosed | payrollId, payrunPeriodId, periodStart, periodEnd |
- The API doesn't currently document a distinct payload shape for
PayrunPeriodFinalizedorPayoutCancellationRequestedbeyond the common fields above - treat any extra fields on those as undocumented until confirmed - Webhook payloads are thin: they tell you that something happened, not the resulting data - for a closed or finalized payrun period, fetch the actual documents separately, see Outputs
Security
- Verify requests really come from Ason: they carry
X-Ason-Signature: sha256=<signature>, an HMAC-SHA256 over the raw body using your webhooksecretas the key - recompute it and compare to verify
Managing webhooks
| What | Call |
|---|---|
| List webhooks | GET /tenants/{tenantId}/webhooks |
| Create a webhook | POST /tenants/{tenantId}/webhooks |
| Get a webhook | GET /tenants/{tenantId}/webhooks/{webhookId} |
| Update a webhook | PUT /tenants/{tenantId}/webhooks/{webhookId} |
| Delete a webhook | DELETE /tenants/{tenantId}/webhooks/{webhookId} |
| List delivery attempts for a webhook | GET /tenants/{tenantId}/webhooks/{webhookId}/messages |
Each delivery attempt (GET /tenants/{tenantId}/webhooks/{webhookId}/messages) records the payload that was sent, when, and the response status/body your endpoint returned - useful for debugging a webhook that isn't arriving.
Testing
In the sandbox environment, finalization of a payrun period is faked: shortly after you close the period, a PayrunPeriodFinalized event fires with a document for each category that would normally come from Swissdec submission.