Skip to main content
If you provide clientWebhookUrl when creating a case, Offload sends JSON POST requests when the case reaches one of its outward-facing async states.

​
Events You Can Receive

EventWhen it is sent
case.completedThe worker marked the case COMPLETED.
case.failedThe worker or AgentMail event handler marked the case FAILED.
case.input_neededThe worker paused the case and needs input from your app.
There are no webhook events for:
  • case creation
  • case accepted
  • case resumed after input
  • case currently running

​
Delivery Behavior

The current implementation sends webhooks like this:
  • method: POST
  • header: content-type: application/json
  • body: serialized JSON event envelope
  • success rule: any HTTP 2xx
  • retry behavior: none in application code
  • signing: none
If the request fails or returns a non-2xx, Offload logs the failure and drops it.
This is the most important webhook constraint in the current implementation: delivery is best-effort, single-attempt, and unsigned. Use HTTPS, dedupe with event_id, and run a polling reconciliation job for important workflows.

​
Event Envelope

{
  "event_id": "evt_4fc5904d-0e44-4ed3-aa57-c4a47ad0ae4f_case_completed_1774131900000",
  "event_type": "case.completed",
  "timestamp": 1774131900000,
  "data": {}
}
event_id is deterministic for a specific case update:
  • it includes the case ID
  • it includes the event type
  • it includes the case updatedAt timestamp
That makes it a good dedupe key on your side. 
export async function POST(request: Request) {
  const event = await request.json();

  // 1. Deduplicate by event_id
  // 2. Persist the full payload
  // 3. Queue your own downstream work
  // 4. Return a fast 2xx

  return new Response(null, { status: 204 });
}

​
Attachment Handling

Webhook payloads include attachment metadata in data.attachments, but not a durable file URL. If you need the file:
  1. read attachmentId from the webhook payload
  2. call GET /cases/{id}/attachments/{attachmentId}
  3. use the returned downloadUrl before expiresAt

​
Metadata Handling

If you passed metadata when creating the case, Offload includes it in webhook payloads. This is useful because GET /cases/{id} does not currently return metadata.

​
Reconciliation Strategy

For production use, a reliable pattern is:
  1. use webhooks for low-latency updates
  2. store event_id
  3. periodically poll active or recently updated cases
  4. repair any missed terminal or input-needed transitions from polling results