Integration guide

An integrating product owns its business records. Amon Sul owns policy context, execution, and the evidence of the work it runs. Integrate through machine REST routes and event contracts, and preserve authenticated tenant, lane, association, entity, and run identity throughout the process.

Inbound workflow

1. Obtain an API key for the intended tenant and lane, with read_entities and enqueue scopes as needed. Managed pairings also establish an association UUID.
2. Read the entity type’s statuses (GET /entity-types/:entityType/statuses) before registering records. Confirm the entity type, lane binding, published policy, tracks, and allowed status codes.
3. Register the external identity with POST /entities. Supply metadata and registration evidence meaningful to your product; the engine does not infer domain rules from those keys.
4. Read the entity and its offered sequences. Keep the returned concrete sequence_id, matrix context, role, and input contract together.
5. Send the input object as starting_parameters to POST /enqueue.
6. Save the returned run_id and follow history/events until the result is known.

The API reference gives the request examples, status codes, and exact route map. HTTP 202 is acceptance, not completion. If registration reports a duplicate, inspect the existing identity and policy context before choosing a retry or reconciliation operation.

Outbound CALL and ODATA

A shared executable action names system_code and a relative path. For each execution lane, configure one active External System with that exact code, its target, and its authentication. Stored credentials are decrypted on the server and dispatched through the Platform integration proxy. The test lane never borrows the production connection when resolution fails.

For CALL, use method, request templates, responseMapping, and successCriteria as declared by the action contract. For ODATA, use the relative service path, entity set, operation, key fields, and query/body settings. Metadata helps the editor author a request; an OData-service UUID is not an executable cross-lane connection selector.

Copy the contract-owned CALL and ODATA examples and follow the JSON guide. In particular, timeoutMs is the action configuration key. Legacy direct URLs and UUID connection references require explicit migration, not silent interpretation.

Validate configuration and test with representative data in the intended lane. An action test can make a real outbound request; choose a disposable destination and data if the request mutates it. See execution limits.

Receive webhooks

Configure a lane-owned webhook under Settings → Webhooks, choose the supported event types/filter, and set its destination. A relative destination requires an external-system attachment; an absolute HTTP(S) destination stands alone. A relative destination uses the attached system’s authentication. An absolute URL does not use that system’s authentication, even when an attachment is stored. Events and delivery jobs retain the original lane and association. Delivery uses the integration proxy in both cases.

Payloads use CloudEvents 1.0. Match the configured event contract rather than inventing a parallel event shape. Webhook delivery serializes the event once with JSON.stringify through the shared request-preparation helper, with:

• Content-Type: application/cloudevents+json
• X-Webhook-ID: configured webhook identity
• X-Webhook-Attempt: attempt number
• X-Webhook-Signature: sha256=<hex> when a signing secret is configured

The signature is HMAC-SHA256 of the exact transmitted body bytes. Verify the raw request body before parsing or reserialising JSON. Reject malformed signature lengths before a timing-safe comparison. The receiving framework’s raw-body configuration is part of the integration; hashing JSON.stringify(req.body) is not an equivalent verification procedure.

Store the CloudEvent id as the receiver’s deduplication identity. Apply the business update and record receipt in the same local transaction, or use a local durable inbox. A repeated accepted event should receive a successful acknowledgement without repeating the mutation. Amon’s webhook ID and the CloudEvent id identify different things; an event ID is not necessarily a UUID.

Delivery, retries, and reconciliation

The event processor queues up to three delivery attempts with a one-minute base exponential backoff; retry delays after failures are one and two minutes. The delivery processor classifies failures through Platform’s webhook policy and stops immediately for a nonretryable failure. Final failure records DLQ evidence. Use Webhook Deliveries for attempt/error evidence and supported retry controls.

An execution result and callback receipt are separate facts. Likewise, an HTTP mutation and Amon’s evidence commit are not atomic. For an uncertain response, correlate the run, action reference, integration traffic, and destination audit record before repeating the request. Stronger external guarantees require the destination’s own idempotency or reconciliation contract.