#Two directions of webhooks

Webhooks in Olyron CRM work in two directions. Inbound webhooks are HTTP endpoints Olyron exposes so third-party providers can push events to you in real time — a delivered email, a completed Stripe subscription, an incoming WhatsApp message. Outbound webhooks are HTTP calls Olyron makes to a URL you own, fired as a step inside an automation workflow.

• Inbound — providers POST to /api/webhooks/* and other receiver routes; Olyron verifies a signature, resolves the tenant, and writes the event to the database.
• Outbound — an automation workflow's webhook action node sends a JSON POST (or GET/PUT/PATCH) to any URL you configure.

#Inbound endpoints reference

Each integration has its own receiver route with its own signing scheme and secret. These are the endpoints currently implemented in the codebase:

#How signatures are verified

Every inbound endpoint reads the raw request body (not parsed JSON) so it can recompute the provider's signature exactly. Requests that fail verification are rejected with a 401 or 403 before any database write.

Per-provider schemes

• Stripe — the stripe-signature header is validated against STRIPE_WEBHOOK_SECRET. A missing signature returns 400; a failed processing result returns 400. If STRIPE_WEBHOOK_SECRET is not set, the handler refuses with Webhook secret not configured.
• Resend — validated with the Svix library using the svix-id, svix-timestamp, and svix-signature headers against RESEND_WEBHOOK_SECRET. An invalid signature returns 401.
• LinkedIn — the x-li-signature: t=<unix>,v1=<hex> header is HMAC-SHA256 verified over <t>.<rawBody> using LINKEDIN_WEBHOOK_SECRET, with a 300-second timestamp-skew tolerance and a constant-time compare. A missing secret returns 503; a bad signature returns 401.
• WhatsApp — the x-hub-signature-256 header is HMAC-SHA256 verified against WHATSAPP_APP_SECRET. If that secret is unset the check is skipped (a dev-only fallback that must not be relied on in production).
• Twilio — the X-Twilio-Signature header is recomputed as an HMAC-SHA1 base64 digest over the request URL plus sorted form parameters, keyed by TWILIO_AUTH_TOKEN.

// Header shape: x-li-signature: t=<unix>,v1=<hex hmac sha256>
const expected = createHmac("sha256", secret)
  .update(`${t}.${rawBody}`)
  .digest("hex");
// constant-time compare against the v1 value, plus a
// timestamp-skew check (default tolerance: 300 seconds)
if (!timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
  return { ok: false, reason: "signature mismatch" };
}

#Verification handshakes

Some providers require a one-time challenge/echo handshake when you register the endpoint. Olyron handles these on the GET method of the receiver route.

1. 1
   WhatsApp (Meta) challenge

   Meta calls GET /api/whatsapp/webhooks/cloud-api?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... Olyron compares hub.verify_token to WHATSAPP_WEBHOOK_VERIFY_TOKEN and echoes hub.challenge back on match, otherwise returns 403. Set the same token string in both places.
2. 2
   LinkedIn challenge

   A GET /api/webhooks/linkedin?challenge=<value> request echoes the challenge value back as text/plain, satisfying the provider handshake.
3. 3
   Confirm delivery

   After the handshake succeeds, send a test event from the provider dashboard and check that the corresponding record appears (an email event row, a WhatsApp message, a LinkedIn activity).

#What inbound events become

Verified events are normalized and written to tenant-scoped tables. For example, the Resend receiver looks up the original send by provider_message_id in email_messages, then routes by event type:

LinkedIn events are mapped to strict activity kinds (for example INVITATION_SENT becomes linkedin_connection_sent), resolved to a tenant via the linkedin_accounts table, and inserted into linkedin_events in batches of up to 500 rows. Events whose account cannot be matched are counted as unmatched and dropped rather than stored — LinkedIn fans out events for shared resources you may not own.

#Sending outbound webhooks from workflows

To notify an external system when something happens in your CRM, add a webhook action node to an automation workflow. When the workflow runs, Olyron makes an HTTP request to the URL you configured with a JSON body describing the record.

1. 1
   Add a webhook action node

   In the workflow builder, add an action node and choose the webhook type. Configure the URL, the HTTP method (GET, POST, PUT, or PATCH), and optional custom headers as a JSON object (for example an Authorization bearer token).
2. 2
   Understand the payload

   For non-GET methods, Olyron sends Content-Type: application/json plus your custom headers, and a body containing the tenant id, record id, module, and the workflow's variable bag.
3. 3
   Read the result

   The node reports success based on the HTTP response being 2xx and records a message like Webhook POST https://... → 200. A non-2xx status or a network error marks the step failed.

tenant_idstring

The tenant the record belongs to.

record_idstring

The id of the record that triggered the workflow.

modulestring

The CRM module the record lives in (for example leads or contacts).

variablesobject

The workflow variable bag assembled during the run.

{
  "tenant_id": "b2c9...e41",
  "record_id": "d18f...a03",
  "module": "leads",
  "variables": {
    "lead_name": "Jane Advisor",
    "stage": "qualified"
  }
}

#Troubleshooting and limits