Webhooks

Using webhooks (see https://en.wikipedia.org/wiki/Webhook), you can have your external systems notified in real time when specific events occur in your atfinity tenant.

When a trigger fires, atfinity sends an HTTP POST request to the URL(s) you have configured for that trigger. The request body is a JSON object and the following headers are always included:

Header	Description
Content-Type	application/json; charset=UTF-8
X-atfinity-event	The trigger name (e.g. case_created)
X-atfinity-version	The atfinity version that sent the request

Triggers

The following triggers are available. Each trigger can be configured independently with one or more target URLs.

Trigger	When it fires
case_created	A new case is created
case_approved	A case is approved
case_declined	A case is declined
case_finished	A case is finished
case_comment	A comment is added to a case
case_changed	Data within a case is changed
case_state_changed	A case transitions to a different state
case_documents_updated	Documents on a case are generated or deleted
case_proofs_updated	Proofs (file attachments) on a case are uploaded or deleted

Payload

Every webhook request contains a JSON body with the following fields:

Field	Type	Description
trigger	string	The trigger name (e.g. case_created)
case_id	integer	Internal ID of the case
case_user_readable_id	string	Human-readable case identifier
case_name	string	Display name of the case
case_url	string	URL to open the case in the atfinity UI
case_version	integer	Current version number of the case
case_color	string | null	Color label assigned to the case, or null
outcome_instance_id	integer | null	ID of the outcome instance, or null
process_key	string | null	Key of the process the case belongs to, or null

Additional fields by trigger

case_changed

Field	Type	Description
action	string	What kind of change occurred (e.g. updated)

case_state_changed

Field	Type	Description
previous_state_key	string | null	Key of the state the case was in before the transition
current_state_key	string | null	Key of the state the case has transitioned to
transition_key	string | null	Key of the transition that was used

case_documents_updated

Field	Type	Description
document_keys	array of strings	Keys of the documents that were affected
action	string | null	What happened to the documents (e.g. generated, deleted)

Example payload

{
  "trigger": "case_state_changed",
  "case_id": 42,
  "case_user_readable_id": "KYC-0042",
  "case_name": "Acme Corp",
  "case_url": "https://your-tenant.atfinity.app/cases/42",
  "case_version": 7,
  "case_color": "green",
  "outcome_instance_id": 17,
  "process_key": "kyc_process",
  "previous_state_key": "in_review",
  "current_state_key": "approved",
  "transition_key": "approve"
}