Check that the webhook's switch is on, the event is ticked, and your site is on Pro or Scale or in the free trial: on a lower plan the webhook stays saved but nothing is sent. Then check that your address answers within 10 seconds with a 2xx status and doesn't redirect, for example to a version with or without www.
API & Webhook Integrations
Connect your site to your own code or to an automation tool such as Zapier or Make. An API key lets a tool add and manage your site's members and access groups; a webhook tells a tool when something happens on your site, such as a new member signing up.
You set up both on the Integrations page of your site dashboard (under Advanced). They are part of the Pro and Scale plans and of the 14-day free trial, and only Owners of your team can create or change them. The page also shows your site's Stripe connection, which you set up on the Paywall page.
API keys
A key works only for the site you create it on, and a site can have 10 active keys.
Create a key
On the Integrations page, click Create Key.
Under Name, enter what the key is for, for example the tool that will use it.
Click Create Key.
Copy the key into your tool.
You can copy it again later: open the menu at the end of the key's row and choose View Key.
Manage your keys
The menu at the end of each key's row holds the other actions. The row also shows when the key was created and when it was last used.
Rename: the key keeps working.
Roll Key: revokes the key and creates a new one with the same name. Requests with the old key fail at once, so update your tool with the new one.
Revoke: the key stops working at once. You can't undo this. The key stays in the list as Revoked and no longer counts toward the 10.
Delete: removes the key from the list, and it stops working.
Make requests with a key
Send the key as a bearer token in the Authorization header of every request. Every address starts with https://api.sotion.so/api/v1:
curl https://api.sotion.so/api/v1/members \
-H "Authorization: Bearer so_your_api_key"The REST API reference lists every request with its fields and errors.
Each key can make 300 reads and 60 changes a minute.
Adding a member through the API sends them no email. Send them a login link through the API when they should get one.
Webhooks
A webhook sends a message to a web address of yours each time one of the events you chose happens on your site. In an automation tool, use the address its webhook trigger gives you.
Add a webhook
On the Integrations page, click Add Webhook.
Enter a Name and the URL. The URL must start with
https://and be reachable from the internet.Under Events, tick the events to send.
Leave Signing Secret empty to have one generated, or enter your own of at least 16 characters.
Click Create Webhook, then copy the signing secret.
A site can have 10 webhooks. Your tool can use the signing secret to check that a message came from us, as Verifying signatures shows.
Which events we send
Event | When we send it |
|---|---|
Member Created ( | A member is added on the Members page or with the API's create-member request or its bulk create, signs up on your login page, or buys access through Stripe with an email that isn't a member yet |
Member Updated ( | A member's details are changed on the Members page or through the API, or a Stripe purchase or cancellation changes a current member's paid status |
Member Login ( | A member signs in with an emailed link or code |
Member Deleted ( | A member is deleted on the Members page or through the API |
Access Group Created, Updated, Deleted | An access group is created, renamed or given a new description, or deleted, on the Access Groups page or through the API |
Access Group Member Added, Removed | A member is added to or removed from an access group on the Members or Access Groups page, through the API, or by a Stripe purchase or cancellation that changes a current member's paid groups |
When a new member joins with access groups, the groups come in Member Created, not as separate Access Group Member Added events.
What we send
Each message is a POST request with a JSON body, signed with the webhook's signing secret. Your address has to answer within 10 seconds with a 2xx status, such as 200 OK. If it doesn't, we try again up to three more times, then drop the message.
We don't follow redirects, so an address that redirects gets nothing. The fields of each event are in Event Payloads.
Manage your webhooks
The switch on a webhook's row turns it off and on. Events that happen while it is off are never sent, not even after you turn it back on.
Edit: change the name, the URL or the events.
View Secret: shows the signing secret. Set Custom there replaces it with one you enter.
Regenerate Secret: replaces the secret with a new one. Messages are signed with the new secret from then on, so update your tool's copy.
Delete: no more messages go to the webhook's URL.
Troubleshooting
My webhook receives nothing
My requests fail with "Invalid or missing API key."
The Authorization header is missing or isn't in the form Bearer so_…, or the key was deleted. Copy the current key with View Key. A revoked or rolled key gets "API key has been revoked." instead.
My requests fail with "API access requires the Pro plan or higher."
Your plan no longer includes integrations, for example after the free trial ends. Your keys and webhooks are kept, and requests work again once you move to Pro or Scale.
My requests fail with "No API endpoint matches"
The address doesn't start with https://api.sotion.so/api/v1.
View Key shows a message instead of the key
The key was created before keys could be viewed again. Roll it to get a new key you can view.
Create Key or Add Webhook is greyed out
Only Owners can create them, and a site holds at most 10 active keys and 10 webhooks.
Was this helpful?
Was this helpful?