# Eggtimer.app + Zapier

A completed timer can POST an event to a Zapier Catch Hook. This release supports hooks.zapier.com Catch Hook URLs only. It uses a same-origin server relay so the hook does not depend on browser-to-Zapier CORS support. No Zapier API key is needed. Webhooks by Zapier Catch Hook requires an eligible paid Zapier plan; see [Zapier's guide](https://help.zapier.com/hc/en-us/articles/8496288690317-Trigger-Zap-workflows-from-webhooks).

## Set it up

1. In Zapier, choose Webhooks by Zapier as the trigger, then Catch Hook. Copy the hook URL.
2. In Eggtimer.app, open Connect Zapier and paste that URL.
3. Check Send my next completed timer to this hook and connect. This enables one completion delivery.
4. To test, reopen the panel, check the test acknowledgment, and click Send test event. A test can run the actions configured in your Zap.
5. In Zapier, test the trigger, map the event fields to the next action, and publish your Zap when ready.

Changing recipes disarms the connection. A test uses timer.test; a real completion uses timer.completed. Use a filter in Zapier if test events should not reach downstream actions. No test or real event is sent merely by importing a recipe, opening a URL, or opening the connection panel.

## Payload

```json
{"version":1,"event":"timer.completed","event_id":"unique-run-id","title":"Tea, then breathe","duration_seconds":240,"completed_at":"2030-01-01T10:00:00.000Z","source":"eggtimer.app"}
```

completed_at is an ISO UTC timestamp for the timer's deadline; it can precede actual delivery if the device slept. duration_seconds is the configured total duration, excluding pauses. event_id identifies the run. For automatic sequences, an event is sent after the final step. The Focus tab finishes a work or break session separately.

## Delivery and privacy

Keep the browser tab open. The browser observes completion and calls the server relay; there is no persistent background scheduler. A sleeping device can delay delivery. Reloading or closing the tab drops the connection. The URL is held only in tab memory, is sent to the relay when delivering, and is not deliberately stored or logged by the application. It is never in recipe exports or shared links. Hosting/network providers may process normal request data.

Zapier accepted means its HTTP endpoint returned success. It does not prove that later Zap actions succeeded; check Zap history. An error or timeout can mean the outcome is uncertain. There are no automatic delivery retries. Check Zapier before manually retrying; the same event_id is retained, but Zapier does not automatically deduplicate it for you.

This relay endpoint is a first-party UI endpoint, not a general public webhook API. It accepts only same-origin JSON requests with a validated target and bounded event payload. Arbitrary webhook providers, scheduled delivery after browser closure, persistent secret storage, inbound webhooks, and delivery guarantees are not supported in this release.


## Create timer links from a Zap

The other direction works through the public link API: a Zap can generate an Eggtimer URL and pass it to an email, task, or message step configured by the person. POST https://eggtimer.app/api/timer-link with Content-Type: application/json and a JSON body such as {"duration":"25m","label":"Focus"}. Map the response's url field into the following step. The countdown starts when someone opens that link, not when Zapier generates it. POST https://eggtimer.app/api/recipe-link with {"recipe":RECIPE_OBJECT} for custom routines; those links preview and wait for Start. See [OpenAPI](https://eggtimer.app/openapi.json) and the [AI/API guide](https://eggtimer.app/ai.html).

These are HTTP API calls, not a published Eggtimer app in the Zapier directory. Use Webhooks by Zapier or another suitable HTTP request action; the current Webhooks by Zapier plan requirements apply. No authentication is required for public link generation. Never include hook credentials in the recipe or link. These link calls cannot start a running browser timer or arm completion delivery. For a real countdown that runs without a browser, see the separate [authenticated server timer API](https://eggtimer.app/server-timers.md).