Core Concepts

External actions and outbox

Record Stripe, Zendesk, email, Slack, or other external side-effect intents durably before a trusted worker executes them.

Overview

Synapsor never pretends an outside API call can be rolled back by a database transaction. External actions use a transactional outbox pattern: the database validates and records the side-effect intent, then a trusted worker claims it, calls the provider with an idempotency key, and confirms the result back to Synapsor.

Use this for actions such as issuing a refund, sending an email, updating a ticket, changing a CRM deal, or posting a message. The app or worker performs the network call; Synapsor records the durable intent, idempotency key, queue state, run graph link, and audit trail.

The action contract can declare caller-supplied ARG values and HIDDEN session bindings. Hidden values such as tenant_id, principal, and current_customer_id are copied from trusted session context; caller JSON cannot override them.

Approval-required actions move from proposed to queued only after APPROVE EXTERNAL ACTION or the approve external-action API records the reviewer note. Retrying the same approval is idempotent once the action is already queued.

External action events can be part of an agent workflow run. EXPLAIN AGENT RUN shows the step, while synapsor_external_action_events shows the worker-facing queue/status details. A worker must claim an action before confirmation, and the same worker principal must confirm that active, unexpired claim; duplicate terminal confirmations are idempotent only when they match the stored terminal state.

Transactional outbox boundary

The DB commits the intent. The worker performs the side effect and confirms the provider result.

Synapsor

Validates action contract
Computes/stores idempotency key
Queues durable action intent
Links result to run graph

Trusted worker

Claims one queued action
Calls Stripe/Zendesk/etc.
Uses the Synapsor idempotency key
Confirms success or failure

Developer notes

Do not call external providers from the DB engine. Use a trusted worker that claims outbox tasks.
Declare required ARG fields and HIDDEN session bindings so worker payloads have a reviewed shape.
Use idempotency keys for provider calls so worker retries do not duplicate side effects.
Do not pass hidden fields in caller JSON. Synapsor rejects attempts to override hidden session bindings.
Confirm only after an active claim. Synapsor rejects premature confirmations, confirmations after claim expiry, confirmations from another worker principal, and conflicting terminal retries.
Record both success and failure confirmations so EXPLAIN AGENT RUN and system views show the final outcome.
Use approval-required action contracts for side effects that need human review before queueing.

External action SQL

SQL

-- Register the action contract once, like schema.
CREATE EXTERNAL ACTION stripe.issue_refund
DESCRIPTION 'Issue a refund from a trusted worker'
PROVIDER 'stripe'
ARG charge_id VARCHAR REQUIRED              -- caller-supplied provider charge id
ARG amount_cents INT REQUIRED               -- caller-supplied amount
ARG reason VARCHAR                          -- optional caller-supplied reason code
HIDDEN tenant_id FROM SESSION tenant_id     -- trusted tenant scope, not caller JSON
HIDDEN principal FROM SESSION principal     -- trusted actor identity
HIDDEN current_customer_id FROM SESSION current_customer_id -- trusted customer scope
MODE PROPOSE THEN EXECUTE
OUTBOX QUEUE 'billing_external_actions'
REQUIRES EVIDENCE;

-- Propose the action inside a workflow run. run_... comes from BEGIN AGENT RUN.
PROPOSE EXTERNAL ACTION stripe.issue_refund
IN AGENT RUN 'run_...'                     -- Synapsor-produced workflow run id
STEP 'refund_customer'                     -- app/framework step key
IDEMPOTENCY KEY 'refund:T-100:2500'        -- app-provided key, or omit for DB-computed key
WITH JSON '{"charge_id":"ch_123","amount_cents":2500,"reason":"courtesy_waiver"}';

-- If the action contract requires approval, an authorized reviewer queues it.
-- Replace act_... with action_instance_id returned by PROPOSE EXTERNAL ACTION.
APPROVE EXTERNAL ACTION 'act_...'
WITH NOTE 'Reviewed policy evidence and approved the refund action';

-- A trusted worker claims one queued item.
-- The claim expires after LOCK FOR; expired claims must be reclaimed before confirm.
CLAIM EXTERNAL ACTION
FROM QUEUE 'billing_external_actions'
LOCK FOR '60 seconds';

-- The worker calls Stripe/Zendesk/etc. outside Synapsor, then confirms result.
CONFIRM EXTERNAL ACTION 'act_...'
STATUS succeeded
PROVIDER REQUEST ID 're_456'
WITH JSON '{"status":"succeeded","amount_cents":2500}';

Examples

python

from synapsor import Synapsor

db = Synapsor("https://synapsor.ai", api_key=SYNAPSOR_API_KEY)
db.set_session({"tenant_id": "acme", "principal": "support_agent_17"})

run = db.agent_runs.start(
    workflow="billing.refund_review_flow",
    input={"ticket_id": "T-100"},
)

action = run.propose_external_action(
    "stripe.issue_refund",
    step_key="refund_customer",
    arguments={"charge_id": "ch_123", "amount_cents": 2500},
    idempotency_key="refund:T-100:2500",
)

db.external_actions.approve(
    action["action_instance_id"],
    note="Reviewed policy evidence and approved the refund action",
)

task = db.external_actions.claim(
    queue="billing_external_actions",
    worker_id="billing-worker-1",
    lock_seconds=60,
)

# Your worker calls Stripe here with task["idempotency_key"] before the claim expires.
db.external_actions.confirm(
    task["action_instance_id"],
    status="succeeded",
    provider_request_id="re_456",
    response={"status": "succeeded", "amount_cents": 2500},
)