HumanTask API Webhooks

Webhooks

Webhooks is the developer surface for one specific problem: notify software when a physical task changes state so applications do not need to poll continuously. The design has to combine ordinary software concerns with physical latency, evidence and money movement.

Event model

For Event model, prefer a small number of well-defined fields over free-form conventions. The physical worker may read natural-language instructions, but software should get structured values for anything that affects control flow.

Endpoint verification

A production treatment of Endpoint verification needs both the normal path and the exception path. Human execution is reliable only when the client knows what happens when the environment does not match the request.

{
  "id": "evt_123",
  "type": "task.completed",
  "created_at": "ISO_8601",
  "data": {"task_id": "task_123"}
}

Signature validation

Signature validation should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

{
  "id": "evt_123",
  "type": "task.completed",
  "created_at": "ISO_8601",
  "data": {"task_id": "task_123"}
}

At-least-once delivery

At-least-once delivery is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

Retry policy

Retry policy should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Ordering and deduplication

Ordering and deduplication should be documented as an explicit part of this interface. The caller needs to know which fields affect routing, which values are authoritative and which states can change after a human has accepted work.

Event-to-object reconciliation

Event-to-object reconciliation is where the implementation should expose physical-world constraints rather than abstracting them away. If access, timing, identity or evidence changes the result, the schema should say so.

Signature Verification

Webhook signatures should be validated against the raw request payload using documented algorithms and timestamp rules. Verification protects applications from accepting fabricated task-complete events.

Delivery Is Not a Queue Contract

A webhook is a notification, not the only copy of the data. After receiving an event, a client should fetch the canonical task or evidence object. This also handles events that arrive late or out of order.

Replay and Debugging

Developers need event IDs, timestamps and a way to inspect or replay failed deliveries. Without that tooling, debugging a task that completed in the real world but failed to update software becomes unnecessarily difficult.

Error Model

Human execution creates a second failure domain beyond software. Surface that domain with structured reasons so clients can branch intelligently instead of parsing worker notes.

Production Readiness

Test the unhappy path deliberately: invalid scope, no available supply, delayed completion, missing proof and client retry. Real-world APIs are defined as much by those states as by success.

Common Integration Mistake

Webhook consumers must deduplicate events and retrieve the canonical task object before performing irreversible downstream actions.

Next Step

Implement one webhooks flow against the canonical task lifecycle, inspect the real payloads and only then generalize the client for more capabilities or locations.

Implementation Notes for Webhooks

Event model

When implementing event model for Webhooks, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Endpoint verification

When implementing endpoint verification for Webhooks, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Signature validation

When implementing signature validation for Webhooks, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

At-least-once delivery

When implementing at-least-once delivery for Webhooks, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Retry policy

When implementing retry policy for Webhooks, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Ordering and deduplication

When implementing ordering and deduplication for Webhooks, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Event-to-object reconciliation

When implementing event-to-object reconciliation for Webhooks, define the contract in a way that another service can validate without reading hidden UI state. Document required fields, optional fields, state-dependent behavior and at least one exception. Because HumanTask API can create real-world work, every ambiguous write operation should also have a traceable client reference or audit path.

Test Matrix

A Webhooks integration should be tested against more than the happy path. Include a valid request, invalid input, duplicate retry, no matching supply, worker exception, incomplete evidence and cancellation where the interface supports it. The result of each test should be observable in the canonical task object so developers can reconcile UI, API and agent behavior.