Webhook Events

This page documents every webhook event type, its trigger condition, and the payload format.

Payload Format

All webhook events follow the same envelope format:

{
  "event": "task.completed",
  "timestamp": "2026-02-24T14:30:00.000Z",
  "attempt_number": 1,
  "data": {
    // Event-specific data
  }
}

Field	Type	Description
event	string	The event type identifier
timestamp	string	ISO 8601 timestamp of when the event occurred
attempt_number	integer	Delivery attempt number (1 = first attempt)
data	object	Event-specific payload (always includes the relevant resource)

---

Task Events

task.created

Fired when a new task is created via the API.

{
  "event": "task.created",
  "timestamp": "2026-02-24T12:00:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "description": "Take 3 clear photos of the storefront.",
    "category": "photography",
    "status": "pending",
    "budget_cents": 5000,
    "platform_fee_cents": 800,
    "worker_payout_cents": 4200,
    "priority": "normal",
    "location_city": "Brooklyn",
    "location_state": "NY",
    "location_latitude": 40.6782,
    "location_longitude": -73.9442,
    "proof_types": ["photo"],
    "environment": "live",
    "created_at": "2026-02-24T12:00:00.000Z"
  }
}

task.funded

Fired when payment for a task is confirmed via Stripe.

{
  "event": "task.funded",
  "timestamp": "2026-02-24T12:01:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "funded",
    "budget_cents": 5000,
    "updated_at": "2026-02-24T12:01:00.000Z"
  }
}

task.posted

Fired when a funded task is posted and visible to workers.

{
  "event": "task.posted",
  "timestamp": "2026-02-24T12:02:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "posted",
    "location_city": "Brooklyn",
    "location_state": "NY",
    "updated_at": "2026-02-24T12:02:00.000Z"
  }
}

task.assigned

Fired when a worker accepts and is assigned to the task.

{
  "event": "task.assigned",
  "timestamp": "2026-02-24T12:30:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "assigned",
    "worker_id": "w1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
    "worker_name": "Marcus T.",
    "assigned_at": "2026-02-24T12:30:00.000Z",
    "updated_at": "2026-02-24T12:30:00.000Z"
  }
}

task.started

Fired when the assigned worker checks in at the task location (GPS verified).

{
  "event": "task.started",
  "timestamp": "2026-02-24T13:00:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "in_progress",
    "worker_id": "w1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
    "started_at": "2026-02-24T13:00:00.000Z",
    "updated_at": "2026-02-24T13:00:00.000Z"
  }
}

task.proof_submitted

Fired when a worker submits proof of task completion.

{
  "event": "task.proof_submitted",
  "timestamp": "2026-02-24T13:45:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "proof_submitted",
    "worker_id": "w1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
    "proof": {
      "id": "p1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
      "type": "photo",
      "attempt_number": 1,
      "geo_valid": true,
      "distance_from_task_meters": 142,
      "created_at": "2026-02-24T13:45:00.000Z"
    },
    "updated_at": "2026-02-24T13:45:00.000Z"
  }
}

task.completed

Fired when a proof is approved and the task is marked complete. The worker payout has been initiated.

{
  "event": "task.completed",
  "timestamp": "2026-02-24T14:30:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "completed",
    "worker_id": "w1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
    "budget_cents": 5000,
    "worker_payout_cents": 4200,
    "completed_at": "2026-02-24T14:30:00.000Z",
    "updated_at": "2026-02-24T14:30:00.000Z"
  }
}

task.proof_rejected

Fired when a submitted proof is rejected.

{
  "event": "task.proof_rejected",
  "timestamp": "2026-02-24T14:30:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "proof_rejected",
    "worker_id": "w1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
    "proof": {
      "id": "p1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
      "type": "photo",
      "attempt_number": 1,
      "rejection_reason": "Photo is blurry and signage is not readable.",
      "reviewed_at": "2026-02-24T14:30:00.000Z"
    },
    "attempts_remaining": 2,
    "updated_at": "2026-02-24T14:30:00.000Z"
  }
}

task.cancelled

Fired when a task is cancelled by the developer.

{
  "event": "task.cancelled",
  "timestamp": "2026-02-24T15:00:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "cancelled",
    "cancelled_at": "2026-02-24T15:00:00.000Z",
    "updated_at": "2026-02-24T15:00:00.000Z"
  }
}

task.expired

Fired when a posted task expires without being assigned (no worker accepted).

{
  "event": "task.expired",
  "timestamp": "2026-02-25T12:00:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "expired",
    "deadline": "2026-02-25T12:00:00.000Z",
    "updated_at": "2026-02-25T12:00:00.000Z"
  }
}

task.disputed

Fired when either the developer or worker opens a dispute.

{
  "event": "task.disputed",
  "timestamp": "2026-02-24T16:00:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "disputed",
    "dispute": {
      "id": "disp_a1b2c3d4e5f6",
      "opened_by": "developer",
      "reason": "The photos do not match the task requirements.",
      "evidence_deadline": "2026-02-26T16:00:00.000Z",
      "created_at": "2026-02-24T16:00:00.000Z"
    },
    "updated_at": "2026-02-24T16:00:00.000Z"
  }
}

task.refunded

Fired when a task is refunded (after cancellation, expiration, or dispute resolution).

{
  "event": "task.refunded",
  "timestamp": "2026-02-24T17:00:00.000Z",
  "attempt_number": 1,
  "data": {
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "title": "Photograph storefront at 123 Main St",
    "status": "refunded",
    "budget_cents": 5000,
    "refund_amount_cents": 5000,
    "refund_reason": "All proof attempts exhausted",
    "updated_at": "2026-02-24T17:00:00.000Z"
  }
}

---

Worker Events

worker.verified

Fired when a worker completes KYC verification and is now eligible to accept tasks.

{
  "event": "worker.verified",
  "timestamp": "2026-02-24T10:00:00.000Z",
  "attempt_number": 1,
  "data": {
    "worker_id": "w1a2b3c4d5e6f1a2b3c4d5e6f1a2b3c4",
    "worker_name": "Marcus T.",
    "city": "Brooklyn",
    "state": "NY",
    "skills": ["photography", "data_collection"],
    "verified_at": "2026-02-24T10:00:00.000Z"
  }
}

info

The worker.verified event is useful for developers who want to track the supply of available workers in their target areas.