Webhooks
Webhooks let your application hear about changes in OnEarly without polling. When an event happens, OnEarly sends a signed HTTP POST with a JSON body to every webhook subscribed to that event's topic.
Personal and group webhooks
A webhook belongs either to you or to a group. That decides which events it receives.
- Personal webhooks receive events for changes you make as yourself.
- Group webhooks receive the group's events: changes made as the group, and changes to the group and its membership.
Managing webhooks
Webhooks are managed in the OnEarly app:
- Personal webhooks under Account → Developer.
- Group webhooks under Group Settings → Developer. You must be an admin of the group.
For each webhook, enter an endpoint URL and choose at least one event. You can change the URL or the events later, or delete the webhook.
The endpoint must be a public https URL. Addresses that point at private or local networks, such as localhost, private IP ranges, link-local addresses, or hostnames ending in .local, .internal, .intranet, .corp or .lan, are refused.
The app shows the webhook's signing secret once, when you create the webhook. Store it securely, for example in your secret manager or an environment variable. If you lose it, delete the webhook and create a new one.
Events
Each webhook subscribes to one or more topics. Available on shows which webhooks can receive a topic: User for personal webhooks, Group for group webhooks, Both for either. The app's event picker offers only the topics a webhook can receive. Group webhooks can also offer topics for specific integrations, which this page doesn't list.
Content
Delivered to whoever made the change. A change made as a group, with the group's API key or by a member acting as the group, reaches the group's webhooks. A change a member makes as themselves reaches their own personal webhooks, not the group's.
| Event | Topic | Description | Available on |
|---|---|---|---|
| Created | com.onearly.content.created | Content is created. | Both |
| Updated | com.onearly.content.updated | A new version of a piece of content is saved. | Both |
| Deleted | com.onearly.content.deleted | Content is deleted. | Both |
| Shared | com.onearly.content.shared | Content is shared with one or more people or groups. | Both |
Group
Delivered to the group, whoever made the change.
| Event | Topic | Description | Available on |
|---|---|---|---|
| Updated | com.onearly.group.updated | A group's details are updated. | Group |
Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.
POST /webhooks/onearly HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: OnEarly/1.0
x-onearly-event-id: 2b7d4e91-0c3a-4f6b-9e85-7a1d2c4b6e03
x-onearly-timestamp: 2026-10-14T02:05:48Z
x-onearly-signature: v0=562ca44c0c898868b4687c61ace99bdc1959ff481616fa1e98a107a73e3406e8
x-onearly-topic: com.onearly.group.updated
{
"event_id": "2b7d4e91-0c3a-4f6b-9e85-7a1d2c4b6e03",
"occurred_at": "2026-10-14T02:05:47.120Z",
"actor_uuid": "4b1f6c2e-8a0d-4e3b-9f57-2c6d8e1a0b93",
"actor_type": "USER",
"group_uuid": "6d2f8a14-3b9e-4c57-a0d1-8e4b2c7f9a35",
"changed_fields": [
"name",
"description"
]
}
Membership
Delivered to the group, whoever made the change.
| Event | Topic | Description | Available on |
|---|---|---|---|
| Invited | com.onearly.membership.invited | Someone is invited to the group. | Group |
| Accepted | com.onearly.membership.accepted | Someone accepts an invitation. | Group |
| Declined | com.onearly.membership.declined | Someone declines an invitation. | Group |
| Added | com.onearly.membership.added | Someone is added to the group directly. | Group |
| Removed | com.onearly.membership.removed | Someone is removed from, or leaves, the group. | Group |
Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.
POST /webhooks/onearly HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: OnEarly/1.0
x-onearly-event-id: 5e1a8c3f-7d24-4b90-a6e1-3f8c2d5b7a19
x-onearly-timestamp: 2026-10-14T02:11:31Z
x-onearly-signature: v0=782473b8330f2913da5ffdcf42e98591cfa009df649d8f5c48770d65b3f08d6a
x-onearly-topic: com.onearly.membership.added
{
"event_id": "5e1a8c3f-7d24-4b90-a6e1-3f8c2d5b7a19",
"occurred_at": "2026-10-14T02:11:30.004Z",
"actor_uuid": "4b1f6c2e-8a0d-4e3b-9f57-2c6d8e1a0b93",
"actor_type": "USER",
"group_uuid": "6d2f8a14-3b9e-4c57-a0d1-8e4b2c7f9a35",
"user_actor_uuid": "f2c84a61-9e3d-4b17-8a05-6d1e3c9b7f42",
"role_uuids": [
"a6d3f1b8-2e47-4c9a-b0e5-8f1c3d6a9b27"
]
}
Sharing
Delivered to whoever made the change, as for Content.
| Event | Topic | Description | Available on |
|---|---|---|---|
| Revoked | com.onearly.sharing.revoked | A share is revoked. | Both |
| Permissions updated | com.onearly.sharing.permissions-updated | A recipient's permissions on shared content change. | Both |
Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.
POST /webhooks/onearly HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: OnEarly/1.0
x-onearly-event-id: 8c4f2a7d-1b5e-4e93-9d60-2a7b4c8e1f35
x-onearly-timestamp: 2026-10-14T03:40:13Z
x-onearly-signature: v0=5d928655af95d6a60d274e65fa633998dcb49e9215c147f49d581c22a1a694f0
x-onearly-topic: com.onearly.sharing.revoked
{
"event_id": "8c4f2a7d-1b5e-4e93-9d60-2a7b4c8e1f35",
"occurred_at": "2026-10-14T03:40:12.660Z",
"actor_uuid": "6d2f8a14-3b9e-4c57-a0d1-8e4b2c7f9a35",
"actor_type": "GROUP",
"content_uuid": "9a2e4c71-5b3d-4f08-8e6a-1d7c0b2f4e95",
"revoked_content_uuids": [
"9a2e4c71-5b3d-4f08-8e6a-1d7c0b2f4e95"
],
"kept_content_uuids": [],
"revoked_principal_type": "USER",
"revoked_principal_uuid": "f2c84a61-9e3d-4b17-8a05-6d1e3c9b7f42",
"revoked_scope_uuid": null,
"include_descendants": true
}
Access grant
Delivered to whoever made the change, as for Content. Access grants are share links.
| Event | Topic | Description | Available on |
|---|---|---|---|
| Created | com.onearly.access-grant.created | A share link is created. | Both |
| Updated | com.onearly.access-grant.updated | A share link is changed. | Both |
| Revoked | com.onearly.access-grant.revoked | A share link is revoked. | Both |
Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.
POST /webhooks/onearly HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: OnEarly/1.0
x-onearly-event-id: 3d9e6b1a-4c72-4f8d-a1b3-5e7f9c2d4a68
x-onearly-timestamp: 2026-10-14T04:02:56Z
x-onearly-signature: v0=3b41f56356eb0df5a269c5d7b593541085911d7c8da21dd06fb7cc2da66ddc8f
x-onearly-topic: com.onearly.access-grant.created
{
"event_id": "3d9e6b1a-4c72-4f8d-a1b3-5e7f9c2d4a68",
"occurred_at": "2026-10-14T04:02:55.318Z",
"actor_uuid": "4b1f6c2e-8a0d-4e3b-9f57-2c6d8e1a0b93",
"actor_type": "USER",
"grant_uuid": "7b2e5d8a-1f4c-4a93-8e6b-0d3f6a9c2e57",
"content_uuid": "9a2e4c71-5b3d-4f08-8e6a-1d7c0b2f4e95",
"item_content_uuids": [
"9a2e4c71-5b3d-4f08-8e6a-1d7c0b2f4e95"
],
"permissions": [
"READ"
],
"permission_mask": 1,
"grant_type": "LINK",
"expires_at": "2026-10-21T04:02:55.000Z",
"has_pin": false
}
User
Delivered only to your own personal webhooks.
| Event | Topic | Description | Available on |
|---|---|---|---|
| Profile updated | com.onearly.user.profile-updated | Your profile is updated. | User |
Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.
POST /webhooks/onearly HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: OnEarly/1.0
x-onearly-event-id: 9a6c3e8f-2d51-4b7a-8f04-6c1e9b3d5a72
x-onearly-timestamp: 2026-10-14T05:17:04Z
x-onearly-signature: v0=e505f11b5955b799cd34472d4704255361b072567fb39c6b88f2c2dd88044685
x-onearly-topic: com.onearly.user.profile-updated
{
"event_id": "9a6c3e8f-2d51-4b7a-8f04-6c1e9b3d5a72",
"occurred_at": "2026-10-14T05:17:03.941Z",
"actor_uuid": "4b1f6c2e-8a0d-4e3b-9f57-2c6d8e1a0b93",
"actor_type": "USER",
"user_uuid": "4b1f6c2e-8a0d-4e3b-9f57-2c6d8e1a0b93",
"profile_content_uuid": "d4a7c2e9-5b18-4f6d-9a03-7e2c5b8f1d64",
"changed_fields": [
"phoneNumber"
],
"email_changed": false,
"phone_changed": true
}
Request format
Every delivery is a POST with Content-Type: application/json and User-Agent: OnEarly/1.0.
Headers
Header names are case-insensitive. Your framework may show them as, for example, X-Onearly-Event-Id.
| Header | Description |
|---|---|
x-onearly-event-id | The event's unique ID. Matches event_id in the body and stays the same on every retry. |
x-onearly-timestamp | When this delivery attempt was sent, in UTC to the second, for example 2026-10-14T01:21:11Z. It changes on every retry, and the signature doesn't cover it. For when the change happened, use occurred_at in the body. |
x-onearly-signature | v0= followed by the hex-encoded HMAC-SHA256 of the raw body. If it holds more than one signature, they are comma-separated after a single v0=. See Verifying signatures. |
x-onearly-topic | The event's topic, for example com.onearly.content.created. |
Payload
Every payload starts with the same envelope fields, followed by the topic's own fields.
| Field | Description |
|---|---|
event_id | The event's unique ID. The same on every retry, so use it to de-duplicate. |
occurred_at | When the change happened, in ISO 8601 UTC. |
actor_uuid | The person or group that made the change. |
actor_type | The kind of actor that made the change: USER, GROUP, GROUP_MEMBER, AGENT or SYSTEM. See Actors. |
scope_uuid | Only when actor_type is GROUP_MEMBER: the group the member acted in. |
Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.
POST /webhooks/onearly HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: OnEarly/1.0
x-onearly-event-id: 0f3c9b2e-6a41-4d8e-b7f5-1c2d3e4f5a6b
x-onearly-timestamp: 2026-10-14T01:21:11Z
x-onearly-signature: v0=5ef905463ac3e03a4e45491a2b6db09206589192ff3f82cfc7bf9505287af8c9
x-onearly-topic: com.onearly.content.created
{
"event_id": "0f3c9b2e-6a41-4d8e-b7f5-1c2d3e4f5a6b",
"occurred_at": "2026-10-14T01:21:09.482Z",
"actor_uuid": "4b1f6c2e-8a0d-4e3b-9f57-2c6d8e1a0b93",
"actor_type": "USER",
"nodes": [
{
"content_uuid": "9a2e4c71-5b3d-4f08-8e6a-1d7c0b2f4e95",
"lineage_uuid": "c3f0a8d2-6e14-4b79-a5c1-8d2e7f9b0a46",
"content_type_uuid": "e8b4d1a6-2c97-4f3e-b0d5-7a1c6e9f2b38",
"content_type_name": "Note"
}
]
}
The fields after the envelope depend on the topic:
| Topic | Fields |
|---|---|
content.created, content.updated | nodes[], each with content_uuid, lineage_uuid, content_type_uuid and content_type_name |
content.deleted | nodes[], deleted_content_uuids[], deleted_lineage_uuids[] |
content.shared | shared_content_uuids[], recipient_count, items[], recipients[], access_expires_at, allow_unauthenticated_access |
group.updated | group_uuid, changed_fields[] |
membership.invited | group_uuid, invite_uuid, invited_user_actor_uuid (can be null), status, role_uuids[] |
membership.accepted | group_uuid, invite_uuid, user_actor_uuid, role_uuids[] |
membership.declined | group_uuid, invite_uuid, user_actor_uuid |
membership.added | group_uuid, user_actor_uuid, role_uuids[] |
membership.removed | group_uuid, removed_user_actor_uuid, is_self_removal |
sharing.revoked | content_uuid, revoked_content_uuids[], kept_content_uuids[], revoked_principal_type, revoked_principal_uuid, revoked_scope_uuid, include_descendants |
sharing.permissions-updated | content_uuid, updated_content_uuids[], principal_type, principal_uuid, scope_uuid, new_permissions[], new_mask, previous_mask |
access-grant.created | grant_uuid, content_uuid, item_content_uuids[], permissions[], permission_mask, grant_type, expires_at, has_pin |
access-grant.updated | grant_uuid, content_uuid, permissions[], permission_mask, expires_at, has_pin |
access-grant.revoked | grant_uuid, plus content_uuid and lineage_uuid, which are always null |
user.profile-updated | user_uuid, profile_content_uuid, changed_fields[], email_changed, phone_changed |
The payloads of the topics on this page identify people and groups by UUID. They never contain email addresses or phone numbers.
Verifying signatures
Every delivery carries a signature in x-onearly-signature. Always verify it before acting on the event, so you know the request came from OnEarly and wasn't changed on the way.
- Compute an HMAC-SHA256 of the raw request body. The key is the webhook's signing secret exactly as the app showed it, including the
whsec_prefix. Don't decode it. - Hex-encode the digest.
- Check that the header starts with
v0=, remove that prefix, split the rest on commas, and compare each value with your digest in constant time. Accept the request if any value matches.
The header has one v0= prefix, however many signatures it holds. Here it is with one signature, then with two:
x-onearly-signature: v0=dcc0417bc6f31cca88c3a0d6b8c43abb49589a2a9acbc95dda09f91cc63735b4
x-onearly-signature: v0=313475065227e2bef733913477a7ad820eb1c3721548cd9f83bc7c179899a74b,dcc0417bc6f31cca88c3a0d6b8c43abb49589a2a9acbc95dda09f91cc63735b4
Accept the request if any of the signatures matches.
Only the body is signed. No header is, including x-onearly-timestamp, so the scheme has no signed timestamp to check for freshness. See Replays under Retries, duplicates and ordering.
Node.js
import crypto from 'crypto';
import express from 'express';
function isValidSignature(rawBody, signatureHeader, secret) {
if (!signatureHeader?.startsWith('v0=')) return false;
const expected = Buffer.from(crypto.createHmac('sha256', secret).update(rawBody).digest('hex'));
return signatureHeader
.slice('v0='.length)
.split(',')
.some((candidate) => {
const received = Buffer.from(candidate);
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
const app = express();
app.post('/webhooks/onearly', express.raw({ type: 'application/json' }), (req, res) => {
const secret = process.env.ONEARLY_WEBHOOK_SECRET; // "whsec_...", used as is
if (!isValidSignature(req.body, req.get('x-onearly-signature'), secret)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body);
// Store the event, skipping any event_id already handled, then respond.
res.sendStatus(200);
});
Python
import hashlib
import hmac
def is_valid_signature(raw_body: bytes, signature_header: str | None, secret: str) -> bool:
if not signature_header or not signature_header.startswith("v0="):
return False
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest().encode()
candidates = signature_header[len("v0="):].split(",")
return any(hmac.compare_digest(candidate.encode(), expected) for candidate in candidates)
Go
package webhooks
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"strings"
)
func ValidSignature(rawBody []byte, signatureHeader, secret string) bool {
if !strings.HasPrefix(signatureHeader, "v0=") {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
expected := hex.EncodeToString(mac.Sum(nil))
for _, candidate := range strings.Split(strings.TrimPrefix(signatureHeader, "v0="), ",") {
if hmac.Equal([]byte(candidate), []byte(expected)) {
return true
}
}
return false
}
Verify the signature before parsing the JSON. If your framework parses the body first, for example with express.json(), the bytes can change and the check fails. Use express.raw({ type: 'application/json' }) or your framework's equivalent.
Retries, duplicates and ordering
- Respond quickly. Return a
2xxas soon as you've stored the event, and do the work afterwards. - Failed deliveries are retried with exponential backoff, with the same
event_id. If an endpoint keeps failing, the webhook can be disabled. The app's webhook list marks a disabled webhook Disabled, with the date. - Delivery is at least once. You can receive the same event more than once. Record each
event_idyou process and skip any you've already handled. - Events can arrive out of order. Use
occurred_atto order them, unless the topic's payload carries its own ordering field. - Replays. A valid signature doesn't prove a delivery is fresh: the same body always carries the same signature, and
x-onearly-timestampisn't signed. De-duplicating onevent_idmakes a resent delivery harmless. If you keep processed IDs only for a limited time, also reject events whoseoccurred_atis older than that window.occurred_atis in the body, so the signature covers it, and it stays the same on every retry.