> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withmithras.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Understand process.updated callbacks, signing, and delivery semantics.

# Webhooks

Phonefarm sends public process callbacks using one event type:

```text theme={null}
process.updated
```

## What Gets Sent

Example payload:

```json theme={null}
{
  "event_type": "process.updated",
  "milestone": "accepted",
  "emitted_at": "2026-03-22T08:30:00.000Z",
  "process": {
    "process_id": "3e6f2e7b-4e3c-4c7c-b8d7-0c53d83f9870",
    "process_type": "keyword_warmup",
    "request_id": "warmup-2026-03-22-001",
    "status": "queued"
  }
}
```

## 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:

```text theme={null}
${timestamp}.${rawJsonBody}
```

Algorithm:

```text theme={null}
HMAC-SHA256
```

Example verifier:

```js theme={null}
import crypto from "node:crypto";

export function verifyPhonefarmCallback({ secret, timestamp, rawBody, signature }) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "utf8"),
    Buffer.from(signature, "utf8"),
  );
}
```

## 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.

## Related But Different Outbound Events

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.

## Read Next

* [Authentication](../api/authentication)
* [Get Process](../api/processes-get)
* [Process Lifecycle](../concepts/process-lifecycle)