Webhooks

One action per event

Key the action to the webhook’s event id. A redelivery is the same action:

export async function onPaymentSucceeded(event: { id: string; data: { email: string; invoice: string } }) {
  await invoke.call({
    tool: "gmail.send_email",
    params: {
      to: event.data.email,
      subject: `Payment received for ${event.data.invoice}`,
      body: "Thanks! Your payment went through.",
    },
    agentId: "notification-agent",
    idempotencyKey: `webhook:${event.id}:confirmation`,
  })
}

The second delivery of the same event resolves with status: "duplicate" and the original receipt. The customer gets one email.

Tool names depend on how your workspace connects to your email provider. Run invoke gateway tools to see the tools your workspace has.

Check state before acting on an old event

A payment.succeeded event can arrive after the payment was refunded. Before acting, confirm the state the event describes is still true:

curl -X POST https://api.invokehq.run/state/verify \
  -H "X-API-Key: $INVOKE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "intent": "send_payment_confirmation",
    "required_fields": ["payment_status"],
    "assumed_state": { "payment_status": "succeeded" },
    "current_state": { "payment_status": "refunded" },
    "conditions": { "payment_status": "succeeded" },
    "on_mismatch": "replan"
  }'

Here the payment was refunded, so the answer is "status": "replan_required". Don’t send the confirmation.

Get Started

Core Concepts

Guides

SDK & CLI

Configuration

One action per event

Check state before acting on an old event

Next steps

​One action per event

​Check state before acting on an old event

​Next steps

One action per event

Check state before acting on an old event

Next steps