Webhooks

Pigeon can send each recording to a URL you control. iPhone only for now.

Build your receiver

Pick a host and copy the prompt to your coding agent, or start from the code. If your URL doesn’t answer 200, Pigeon retries for up to 3 days.

export default {
  async fetch(req, env, ctx) {
    const auth = req.headers.get("authorization");
    if (auth !== `Bearer ${env.PIGEON_TOKEN}`) {
      return new Response("bad token", { status: 401 });
    }
    const form = await req.formData();
    // payload is a string part, not a file
    const memo = JSON.parse(form.get("payload"));
    if (memo.event === "test") return new Response("ok");
    const audio = form.get("audio"); // File or null
    // Answer first. Do the slow work after.
    ctx.waitUntil(save(memo, audio, env));
    return new Response("ok");
  },
};

async function save(memo, audio, env) {
  const id = memo.recording_id;
  if (audio) await env.AUDIO.put(`${id}.m4a`, audio);
  // Store memo.transcript by id, then run your agent
  // when memo.transcript_status is "complete".
}

import { waitUntil } from "@vercel/functions";

export async function POST(req) {
  const auth = req.headers.get("authorization");
  if (auth !== `Bearer ${process.env.PIGEON_TOKEN}`) {
    return new Response("bad token", { status: 401 });
  }
  const form = await req.formData();
  // payload is a string part, not a file
  const memo = JSON.parse(form.get("payload"));
  if (memo.event === "test") return new Response("ok");
  // Answer first. Do the slow work after.
  waitUntil(save(memo));
  return new Response("ok");
}

async function save(memo) {
  // Store memo.transcript by memo.recording_id, then
  // run your agent when transcript_status is "complete".
}

Anything that accepts a multipart POST works. Modal takes bodies up to 4 GiB. Val Town takes 100 MB, with a one minute limit per run on the free plan.

Set up webhooks on your phone

1. Open settings and turn on send to webhook.
2. Paste your URL into address.
3. Pigeon fills in secret for you. Tap copy secret and save it as PIGEON_TOKEN on your host (the prompts above show how), or paste your own.
4. Turn on include audio if you want the recording too. It starts off.
5. Tap send test. You should see test delivered.
6. Tap save.

The secret goes out with every request so your server knows it’s you. Pigeon makes a random one when the field is empty. Keep it. Without it, anyone who finds the URL can send to it.

Use the final URL. A redirect can turn the POST into a GET, and Pigeon says the address doesn’t accept recordings.

Turning send to webhook off pauses sending. Recordings made while it’s off aren’t sent.

Try a sample

To see one request before you have a server:

1. Open webhook.site and copy the URL.
2. In Pigeon, turn on send to webhook, paste the URL, clear secret, and tap send test.
3. The request shows up on that page.

webhook.site isn’t our site, and it isn’t yours. Anyone with the link can read what lands there, so don’t send your real secret, a real memo, or anything sensitive.

What you receive

The payload part:

{
  "version": 1,
  "event": "recording",
  "recording_id": "3F2A9C1E-...",
  "recorded_at": "2026-09-30T17:56:06Z",
  "sent_at": "2026-09-30T17:56:09Z",
  "transcript": "Call Sarah about the CTO search...",
  "transcript_status": "complete",
  "transcription_mode": "onDevice",
  "audio_included": false,
  "app": {
    "platform": "ios",
    "version": "1.9",
    "build": "17"
  }
}

New fields can show up later. Ignore any you don’t use.

Responses and retries

Answer within 2 minutes, or Pigeon counts it as no answer. The app shows the status and the start of your error, like HTTP 401: bad token.

After 3 days Pigeon stops trying. The recording stays on the phone, and the app says how many it gave up on.

A memo recorded offline goes out once the phone is back online.

Receiver rules

• Check the secret on every request. Return 401 if it’s wrong.
• Return 200 before you do the slow work. If you answer too late, Pigeon retries and you get the same recording again.
• Save by recording_id, and let the newest sent_at win. The same recording can arrive twice: a retry, or a placeholder and then the real transcript.
• Run your agent once per recording_id, when event is recording and transcript_status is complete.