You will need the API permission to manage API keys and webhooks. Webhooks also need you to have no campus limit.
API and webhooks are available on the Core Plus and Premium plans.
One Church Software offers an official API (Application Programming Interface) and webhooks for connecting third-party applications to your church database. The API gives a third-party application read and write access across nearly the entire system, while webhooks send a real-time message to a URL of your choice when certain events happen inside One Church.
Where to find it
Click the gear icon at the top right of the page (Settings & Tools) and choose API / Webhooks from the Tools/Utilities column.
The page opens with two tabs at the top: API Keys and Webhooks. The View Documentation button at the top of the page opens the full developer reference.
If you also have the Integrations permission, which is account-wide, the Integrations page shows an API & Webhooks card while you hold the API permission.
API Keys
An API key authenticates a third-party application as it makes requests to One Church. Each key carries its own permissions, just like a person, so you can give an integration only the access it needs.
Note: API keys are like passwords. Keep them in secure server-side code and never share them publicly.
Add an API key
On the API Keys tab, click + Add New. The New API Key window opens.
Fill in the fields described below, then click Save.
The API Key Successfully Created window shows the key's token. Copy it and store it somewhere secure. You cannot view the token again once you close the window.
The New API Key window has these fields:
Name - the name of the key. Choose something that makes the integration's purpose obvious, for example "Mailchimp Sync".
Description - an optional note about what the key is for and which application uses it.
Access - controls what data the key can read and write. Choose one of the four options below.
Guest - the same access a typical church member has. Limited to public areas of the system, the person's own profile and giving history.
Super User - unrestricted access, including account billing, subscription and financial data. Use sparingly.
Role Based - choose one or more existing roles. The key gets the combined permissions of all the selected roles. Click choose roles to pick them.
Custom - set permissions exactly the way you want without using a role. Three sub-tabs appear, Permissions, Campuses and Custom Fields, where you can fine-tune access. The Campuses sub-tab sets the key's campus limit.
How an API key's access works
An API key works like a hidden person with its own permissions and campus limit. A few things differ from a staff member:
Campus overrides are not offered for API keys.
A key with a campus limit sees people only inside its limit. Unlike a campus-limited staff member, it does not get a directory view of people at other campuses in its organizations.
Add to Campus is not available to API keys.
A key with a campus limit is refused every webhook action. Who can work with webhooks below explains why.
Without the Permissions Full permission, you cannot grant or remove a Financial permission on a key. The key keeps the Financial permissions it already has, and any change to them is ignored without a message.
Manage existing keys
The API Keys table shows each key's Name, Description, Token, Access level, and who created it. The Token column shows only a short preview of the key for security. To update a key, use the 3-dots menu at the start of its row.
Webhooks
A webhook sends a real-time message from One Church to a URL of your choice when an event happens, for example when a sermon is added or a record is edited. This lets a third-party application react to changes immediately instead of checking the API on a schedule.
The Webhooks tab has two sub-tabs:
Configuration - where webhooks are created and edited.
Activity - a delivery log of every event that has been sent.
Who can work with webhooks
Webhooks have no campus or organization field, and a delivery carries matching records from every organization. Because a webhook cannot be narrowed to the campuses someone is allowed to see, only someone with no campus limit can work with one.
Anyone, or any API key, with a campus limit is refused every webhook action. There is no partial access. The refused actions are:
listing webhooks and reading one
saving and deleting
replaying a delivery and sending a test
viewing the activity log
changing webhook settings
Warning: Use an API key with no campus limit for each webhook. A campus limit on the key, or on you, blocks every webhook action.
Add a webhook
On the Webhooks > Configuration sub-tab, click + Add Webhook. The Add Webhook window opens with two tabs: General and Subscriptions.
Fill in the General tab, described below.
On the Subscriptions tab, choose the events the webhook should listen for. Use the Filter list below field to search the list, or check all / clear all to select events in bulk. At least one subscription must be selected before you can save.
Click Add to create the webhook.
The General tab has these fields:
Name - a label for the webhook. Required.
API Key - the API key the webhook uses. Required. It defaults to the first available key. Choose a key with no campus limit.
Callback URL - the URL on the receiving system that One Church sends event data to. Required.
Send Test - sends a sample event to the Callback URL so you can check the receiver.
Protect webhook URL with basic authentication? - tick the box to require a username and password on the receiving end. Useful when the third-party application supports basic authentication.
Email errors to - one or more email addresses to notify when a delivery fails.
Manage existing webhooks
The Configuration sub-tab lists each webhook with these columns: Name, URL, Events (a count you can click to view the subscriptions), Key, Enabled and Protected. Use the 3-dots menu at the start of a row to edit or delete a webhook.
View webhook activity
The Activity sub-tab is a log of every webhook delivery. Each row shows the ID, the Event that fired, the Webhook that handled it, the Status (the HTTP response code from the receiver), the HTTP Method and the destination URL. Use it to confirm successful deliveries (status 200) or troubleshoot failures.
API documentation
For full reference details, including authentication, available endpoints and request and response formats, click View Documentation at the top of the API / Webhooks page. It opens the official One Church Software API documentation at https://developers.onechurchsoftware.com, where developers can explore the API.
The reference covers hundreds of web services across almost every area of One Church, so most integrations can read and write the data they need through a single API key.