Twenty webhook security, replay, and events

This reference defines the reviewed Twenty inbound webhook boundary. It covers route activation, exact raw-body HMAC, clock and workspace checks, durable nonce replay fencing, deterministic event mapping, local acceptance, and central AIP publication.

Use the metadata guide to create or rotate provider registration. This page starts when an external HTTP delivery reaches the standalone connector host.

Status and route

The route exists only when AIP_TWENTY_WEBHOOK_SECRET_FILE is configured. Enabling it also requires AIP_CONNECTOR_HOST_EVENT_ENDPOINT; otherwise host startup fails.

An external reverse proxy may expose a different HTTPS origin and prefix. It must preserve all three headers and the request body byte for byte when forwarding to the internal route.

What the signature authenticates

The verification equation is:

expected = HMAC-SHA256(
  configured_webhook_secret,
  timestamp_header_bytes || ":" || exact_raw_body_bytes
)

hex_decode(signature_header) == expected

The connector decodes exactly 64 hexadecimal signature characters and uses the HMAC library’s verification method. Uppercase and lowercase hex are accepted.

The nonce is not an HMAC input. It is validated and fenced separately. The HTTP route and header names are also outside the signature input.

Possession of the secret authenticates the timestamp and exact body. It does not prove that Twenty generated a business fact, that the configured provider registration belongs to the expected operator, or that the body is true.

Ingress pipeline

The standalone host processes one delivery in this order:

1. apply the 4 MiB HTTP body limit;
2. require non-empty timestamp, signature, and nonce headers;
3. require a non-empty body no larger than 4 MiB;
4. validate 32 hexadecimal nonce characters;
5. validate 64 hexadecimal signature characters;
6. parse a 1-to-32-digit Unix-millisecond timestamp;
7. require absolute host-clock skew at most 300,000 ms;
8. verify HMAC over timestamp, colon, and exact raw body;
9. durably admit the nonce in the instance replay scope;
10. parse the signed body as a JSON object;
11. validate event name, configured workspace, webhook UUID, and event date;
12. derive a deterministic AIP event;
13. append it to the local event log;
14. durably enqueue it on channel twenty-webhooks;
15. attempt immediate central delivery;
16. return HTTP 200 after durable local acceptance.

Central acknowledgement is optional at step 15. When it is unavailable, the background publisher owns a durably queued batch.

Validate the headers and clock

The timestamp string itself is signed. Reformatting the same instant changes the HMAC input.

Keep host clocks synchronized. The connector does not contact Twenty or a time authority to resolve clock disagreement.

Preserve exact raw-body bytes

The connector computes HMAC before parsing JSON. Whitespace, key order, escaping, number formatting, or a trailing newline changes the signed bytes.

A proxy or middleware must not parse and reserialize the body. It may enforce a smaller ingress limit if it preserves accepted bodies and headers exactly.

Do not log the secret, signature, full body, or mapped event data. The body can contain confidential and personal workspace data.

Validate the signed payload

After HMAC and replay admission, the body must be a JSON object containing:

{
  "eventName": "company.updated",
  "workspaceId": "0190c42f-2d5a-7000-8000-000000000080",
  "webhookId": "0190c42f-2d5a-7000-8000-000000000081",
  "eventDate": "2030-01-03T10:00:00Z"
}

Each named field must be a non-empty string. Additional provider fields remain inside the event data.

eventName accepts 1 through 256 ASCII alphanumeric, ., _, or - characters. It is not restricted to a source-owned event-name enum.

workspaceId must equal the host’s configured workspace string exactly. webhookId must be an RFC 4122 UUID version 1 through 5. eventDate must parse as RFC 3339 and becomes the AIP event’s occurred_at.

A valid signature from another workspace is rejected. The HMAC secret does not replace workspace binding.

Replay state

The standalone host uses a profile-state replay store with:

Every replica of one logical instance must share the same durable runtime database and instance ID. Different instance IDs have independent replay scopes.

Before inserting a nonce, the store removes entries older than the cutoff. It rejects an existing nonce and rejects a new nonce when the live map already contains 100,000 entries.

CAS conflicts yield and retry. Continued contention after 32 attempts is a replay-store failure, not an authentication success.

The connector also contains an in-memory implementation for tests and single-process development. The standalone host constructs the profile-state implementation.

Understand the admission-order boundary

The replay store admits a verified nonce before JSON parsing, payload-field validation, local event-log append, or outbox enqueue.

An authenticated malformed payload therefore consumes its nonce. A failure in the later local event-log or outbox step also occurs after nonce admission.

Repeating the exact delivery with the same nonce then receives a public authentication failure. Provider retry is not the recovery mechanism for a late local failure at this revision.

Preserve host storage evidence and inspect event log, replay state, and outbox before changing state. Escalate according to deployment policy when a verified delivery was fenced but not durably published.

Map the deterministic event

The connector calculates:

digest = SHA-256(webhook_id || ":" || nonce || ":" || signature_header)
event_id = "evt_" || hex(first_16_digest_bytes)
event_kind = "twenty." || eventName

The event records:

The event ID does not include raw-body bytes directly. Signature changes alter the ID, while the replay fence separately owns nonce uniqueness.

Before central publication, the common publisher projects a provider-originated actor into data.upstream_actor. Authenticated central ingress owns the trusted protocol-level event actor and binds it to connector-host signing identity.

Local event log and central outbox

The host appends the deterministic event to its local AIP event log. Duplicate event IDs reuse the log’s accepted event outcome rather than creating a new event identity.

It then durably enqueues one-event batch on channel twenty-webhooks. The publisher derives a stable batch key from normalized channel and event data.

The acknowledgement body reports one of two central outcomes:

A crash after central acknowledgement but before local outbox deletion may resend the same event ID. The central event log is expected to deduplicate that identity.

HTTP 200 proves durable local acceptance or central acknowledgement. It does not always prove that central delivery completed before the response.

Public HTTP responses

The common HTTP body layer can reject an oversized request before the handler. Do not depend on one JSON error code for that proxy or framework-level failure.

The public 401 intentionally collapses validation details. Diagnose through bounded internal telemetry without logging secret or payload content.

Operate and recover the boundary

Do not clear replay state, rotate an instance ID, replace the event ID, or ask for same-nonce replay merely to make a delivery pass. Those actions can weaken deduplication or lose the original failure evidence.

Security and evidence boundaries

Retain:

• host artifact, instance, replica, tenant, workspace, and secret revision;
• redacted provider registration identity;
• receipt time and bounded header validation outcomes;
• deterministic event ID and kind;
• replay-store scope and admission outcome;
• local event-log append identity;
• outbox batch identity and central outcome;
• recovery actions and final central observation.

Do not retain secret bytes, full raw payload, or unredacted personal data in ordinary logs. Store any necessary payload evidence under explicit tenant, access, and retention controls.

Source review establishes this implemented pipeline. It does not establish that a particular deployment, provider registration, artifact, or live event has passed qualification.

Related documentation

• Twenty connector configuration
• Authentication and workspace isolation
• Manage views, layouts, and webhook metadata
• Connector fleet architecture
• Errors and retry decisions