Skip to main content

Webhooks

Phonefarm sends public process callbacks using one event type:

What Gets Sent

Example payload:

Headers

Always sent:
  • Content-Type: application/json
  • User-Agent: phonefarm-callback/1.0
Sent when PHONE_FARM_WEBHOOK_SECRET is configured:
  • X-PhoneFarm-Timestamp
  • X-PhoneFarm-Signature

Signature Verification

Signature input:
Algorithm:
Example verifier:

Delivery Semantics

Callbacks are best-effort:
  • Phonefarm logs callback failure
  • callback failure does not fail the originating API request
  • current edge handlers do not retry callback delivery
For correctness, your integration should:
  1. verify the signature when configured
  2. accept duplicate callback deliveries safely
  3. poll GET /processes/{process_id} for source-of-truth state

Milestones

Current public callbacks include milestones such as:
  • accepted
  • cancel_requested
  • cancelled
  • failed_terminal
Milestones are descriptive markers, not a versioned workflow engine contract. Phonefarm also emits operational telemetry toward UGC Tracker on the runtime side. Those phone-state and session events are not the same contract as public process.updated callbacks.