Outbound Webhooks

Outbound webhooks send Convor events to your HTTPS endpoint. Webhook management requires organization administrator access and the automation_api integration module.

Open Integrations → Webhooks to create endpoints, choose events and site scope, send test payloads, inspect delivery history, edit site bindings, retry failed deliveries, or remove an endpoint from the dashboard.

Use the Webhooks API reference for the equivalent API operations and current request/response schemas.

Endpoint requirements

A production webhook URL must:

• use HTTPS;
• resolve to a public IP address;
• not target localhost, loopback, or a private network;
• accept a JSON POST request;
• return a 2xx response within 10 seconds.

Convor validates the target again at delivery time to reduce DNS-rebinding and server-side request forgery risks.

When creating a webhook through the API, provide a random secret of 16 to 512 characters and store it in your secret manager. Rotate the secret if it is exposed; the rotation endpoint returns the replacement plaintext secret once.

Delivery request

A normal delivery has this body shape:

{
  "event": "message.created",
  "timestamp": "2026-08-03T18:24:31.123Z",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111"
  }
}

The exact data object depends on the event. Use GET /api/webhooks/events for the current event catalog.

Convor sends these headers:

Content-Type: application/json
X-Convor-Signature: sha256=<hex-hmac>
X-Convor-Event: message.created
X-Convor-Payload-Version: 2024-06-01
X-Convor-Delivery-Id: <uuid>

Verify the signature

Verify the signature before parsing or processing the JSON. HMAC input must be the exact bytes received from the network; serializing a parsed object can change whitespace or property order and invalidate the signature.

import {createHmac, timingSafeEqual} from "node:crypto";

export function verifyConvorWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader?.startsWith("sha256=")) return false;

  const suppliedHex = signatureHeader.slice("sha256=".length);
  if (!/^[a-f0-9]{64}$/i.test(suppliedHex)) return false;

  const expected = Buffer.from(
    createHmac("sha256", secret).update(rawBody).digest("hex"),
    "hex"
  );
  const supplied = Buffer.from(suppliedHex, "hex");

  return supplied.length === expected.length
    && timingSafeEqual(supplied, expected);
}

Use your framework's raw-body facility. Do not compare signatures with a normal string equality operation and do not compare against JSON.stringify(parsed).

Processing and deduplication

A receiver should acknowledge quickly and process expensive work asynchronously:

1. Read and size-limit the raw body.
2. Verify X-Convor-Signature.
3. Validate the payload version and event.
4. Atomically record X-Convor-Delivery-Id as the deduplication key.
5. Enqueue application work.
6. Return 2xx.

Webhook delivery is at least once. Network ambiguity or a failed acknowledgement can produce another request for the same delivery. If the delivery ID was already completed, return 2xx without applying the side effect again.

Retries and endpoint health

A failed queued delivery is attempted up to three times with exponential backoff starting at one second. A non-2xx response, timeout, DNS/TLS failure, or blocked target is a failed attempt.

After the final automatic attempt, the delivery is marked failed and can be retried through the delivery API. A webhook is automatically disabled after 10 consecutive failed deliveries. Review delivery history and fix the receiver before re-enabling or retrying sustained failures.

Secret rotation

During a controlled rotation:

1. Call the rotate-secret endpoint and capture the returned secret securely.
2. Deploy the new secret to your receiver immediately.
3. Confirm a signed test delivery.
4. Remove the previous secret from all systems.

The new secret becomes authoritative when rotation succeeds. Do not assume an overlap window where both secrets remain valid.

Provider callbacks are different

OAuth callbacks and inbound provider webhooks for Slack, Messenger, Shopify, Stripe, and other integrations are not customer outbound-webhook endpoints. They are provider-to-Convor protocol routes configured by each integration flow.

Do not call those callback URLs with an organization API key and do not add them to a generic webhook receiver. Complete the provider-specific setup from the relevant integration guide; Convor validates the provider's state, signature, or verification challenge according to that integration.