Documentation · Integrations and agents
API keys and webhooks
Connect EmmauOS to Zapier, Make, n8n or your own code with a church key. Each key has a name, the scopes you tick, and an end date. Webhooks send new results, people and stage moves as they happen.
For: AdminOwner
Keys
On Settings → Connections → AI agents, under API keys, press New key. Give it a name (Zapier for the connect team), tick only the scopes it needs, and choose how long it lives (a year by default). The key shows once; copy it into the tool that will use it. EmmauOS keeps only a fingerprint.
Keys come with Growing and Large. Only an owner or admin makes or revokes one, and every change is in the history with their name. Revoke stops a key at once and removes the webhooks it added.
| Scope | What it allows |
|---|---|
| people:read | People who said the team may contact them: name, email, source and when they were added. |
| people:write | Add a person, or a plain line on their timeline. Nobody is contacted. |
| results:read | Results as gift bands. Never answers, stories or notes. |
| stages:read | Your tracks and where people are on them. |
| stages:suggest | Suggest a stage move. Staff confirm it on the person's page. |
| sources:read | Your sources and their links. |
| webhooks:manage | Add and remove its own webhooks, as Zapier does. |
What a key never sees
A key gets less than an AI agent. It never sees the words of something I have walked through, how someone came to faith, confirmations, conversations, giving, gifts of the Spirit, anyone who may be under 18, or anyone who didn't say the team may contact them. Results come as bands, never a ranking or a maturity score. A key can't send a message, change a stage on its own, or read another church.
Webhooks
Under Webhooks, press Add webhook, paste an https:// address, and tick the events:
| Event | When it is sent |
|---|---|
| result.completed | Someone finishes the assessment. |
| person.added | Someone is added to People. |
| person.stage_changed | Someone moves to a new stage. |
| person.erased | Someone is erased. Only their id is sent, so copies elsewhere can be deleted. |
The signing secret shows once. Each send waits about 20 seconds, then checks the person again, so a result someone keeps private is never sent. A send that fails is tried again for a day, then the webhook pauses and the list says why. Deliveries shows the last 30 days, and Send again retries one.
Webhooks come with every paid plan. A webhook an AI agent prepares waits until an admin copies its secret here.
Sending is yours
EmmauOS never contacts anyone on its own, and a key doesn't change that. When your Zap emails a new person, your church sends that email from your own tool. What you send through your own keys goes where you send it, under your own privacy notice.
For developers
Send the key as Authorization: Bearer eos_key_… to /api/v1/integration. Each key may make 60 requests a minute. Check each webhook with the EmmauOS-Signature header: t= is the time and v1= is an HMAC-SHA256 of t.body with your secret. The API reference lists every route, field and event, with an example. To connect through Zapier, see Zapier.
Try it on your own church
Your assessment link works the minute you sign up. The first 50 people are free, and there is no card to enter.
This page as Markdown, for notes or an AI assistant.