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

Diagram: [Webhook delivery](https://docs.onearly.com/diagrams/api-webhooks.html)

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

:::caution[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.

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

**Example: group.updated**

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

Request:

```http
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 |

**Example: membership.added**

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

Request:

```http
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](#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 |

**Example: sharing.revoked**

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

Request:

```http
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](#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 |

**Example: access-grant.created**

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

Request:

```http
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 |

**Example: user.profile-updated**

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

Request:

```http
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](#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](/core-model/actors). |
| `scope_uuid` | Only 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:

```http
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` |

:::info[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:

```text
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](#retries-duplicates-and-ordering).

### Node.js

```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

```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

```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
}
```

:::warning[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.

Source: https://docs.onearly.com/api/webhooks/
