Skip to main content

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.

Webhook delivery
Webhook delivery

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.

Store the signing secret

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.

EventTopicDescriptionAvailable on
Createdcom.onearly.content.createdContent is created.Both
Updatedcom.onearly.content.updatedA new version of a piece of content is saved.Both
Deletedcom.onearly.content.deletedContent is deleted.Both
Sharedcom.onearly.content.sharedContent is shared with one or more people or groups.Both

Group​

Delivered to the group, whoever made the change.

EventTopicDescriptionAvailable on
Updatedcom.onearly.group.updatedA group's details are updated.Group
Example: group.updated

Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.

Request
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.

EventTopicDescriptionAvailable on
Invitedcom.onearly.membership.invitedSomeone is invited to the group.Group
Acceptedcom.onearly.membership.acceptedSomeone accepts an invitation.Group
Declinedcom.onearly.membership.declinedSomeone declines an invitation.Group
Addedcom.onearly.membership.addedSomeone is added to the group directly.Group
Removedcom.onearly.membership.removedSomeone is removed from, or leaves, the group.Group
Example: membership.added

Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.

Request
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.

EventTopicDescriptionAvailable on
Revokedcom.onearly.sharing.revokedA share is revoked.Both
Permissions updatedcom.onearly.sharing.permissions-updatedA recipient's permissions on shared content change.Both
Example: sharing.revoked

Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.

Request
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.

EventTopicDescriptionAvailable on
Createdcom.onearly.access-grant.createdA share link is created.Both
Updatedcom.onearly.access-grant.updatedA share link is changed.Both
Revokedcom.onearly.access-grant.revokedA share link is revoked.Both
Example: access-grant.created

Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.

Request
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.

EventTopicDescriptionAvailable on
Profile updatedcom.onearly.user.profile-updatedYour profile is updated.User
Example: user.profile-updated

Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.

Request
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.

HeaderDescription
x-onearly-event-idThe event's unique ID. Matches event_id in the body and stays the same on every retry.
x-onearly-timestampWhen 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-signaturev0= 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-topicThe 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.

FieldDescription
event_idThe event's unique ID. The same on every retry, so use it to de-duplicate.
occurred_atWhen the change happened, in ISO 8601 UTC.
actor_uuidThe person or group that made the change.
actor_typeThe kind of actor that made the change: USER, GROUP, GROUP_MEMBER, AGENT or SYSTEM. See Actors.
scope_uuidOnly when actor_type is GROUP_MEMBER: the group the member acted in.
Example: content.created

Signed with the example signing secret whsec_9f8e7d6c5b4a39281706f5e4d3c2b1a0, so you can check your verification code against it.

Request
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:

TopicFields
content.created, content.updatednodes[], each with content_uuid, lineage_uuid, content_type_uuid and content_type_name
content.deletednodes[], deleted_content_uuids[], deleted_lineage_uuids[]
content.sharedshared_content_uuids[], recipient_count, items[], recipients[], access_expires_at, allow_unauthenticated_access
group.updatedgroup_uuid, changed_fields[]
membership.invitedgroup_uuid, invite_uuid, invited_user_actor_uuid (can be null), status, role_uuids[]
membership.acceptedgroup_uuid, invite_uuid, user_actor_uuid, role_uuids[]
membership.declinedgroup_uuid, invite_uuid, user_actor_uuid
membership.addedgroup_uuid, user_actor_uuid, role_uuids[]
membership.removedgroup_uuid, removed_user_actor_uuid, is_self_removal
sharing.revokedcontent_uuid, revoked_content_uuids[], kept_content_uuids[], revoked_principal_type, revoked_principal_uuid, revoked_scope_uuid, include_descendants
sharing.permissions-updatedcontent_uuid, updated_content_uuids[], principal_type, principal_uuid, scope_uuid, new_permissions[], new_mask, previous_mask
access-grant.createdgrant_uuid, content_uuid, item_content_uuids[], permissions[], permission_mask, grant_type, expires_at, has_pin
access-grant.updatedgrant_uuid, content_uuid, permissions[], permission_mask, expires_at, has_pin
access-grant.revokedgrant_uuid, plus content_uuid and lineage_uuid, which are always null
user.profile-updateduser_uuid, profile_content_uuid, changed_fields[], email_changed, phone_changed
Identifiers only

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.

  1. 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.
  2. Hex-encode the digest.
  3. 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
}
Use the raw request body

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 2xx as 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_id you process and skip any you've already handled.
  • Events can arrive out of order. Use occurred_at to 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-timestamp isn't signed. De-duplicating on event_id makes a resent delivery harmless. If you keep processed IDs only for a limited time, also reject events whose occurred_at is older than that window. occurred_at is in the body, so the signature covers it, and it stays the same on every retry.