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 finalised - instead of polling for it.
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).
Creating a webhook requires an admin of the tenant.
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 PayrunPeriodFinalized or PayoutCancellationRequested beyond 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 finalised payrun period, fetch the actual documents separately - see Outputs.
Security
Your endpoint needs to verify that an incoming request really originates from Ason. Requests from Ason carry the header X-Ason-Signature: sha256=<signature>, generated as an HMAC-SHA256 over the raw request body, using the secret you provided when creating the webhook as the key. Recompute the same HMAC on your side and compare it to the header to verify the request.
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 .../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, finalisation 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.