Webhooks

Use webhooks when Meshes should deliver product events to a destination that is not covered by a first-party integration. Webhooks support authenticated requests, custom headers, payload signing, and multiple HTTP methods so your endpoint can verify every delivery.

Supported actions

• Send Webhook delivers the event payload to the configured webhook URL.

Create the connection

1. Open Connections in your Meshes workspace.
2. Click New Connection.
3. Select Webhook.
4. Give the connection a clear name.
5. Enter the destination Webhook URL — must be https://.
6. Choose an HTTP Method (POST, PUT, or PATCH). Defaults to POST.
7. Choose a Payload Format (Wrapped or Raw). Defaults to Wrapped.
8. Configure Authentication if the endpoint requires it (see below).
9. Configure Payload Signing if the endpoint verifies HMAC signatures (see below).
10. Save the connection.

Meshes sends a test request to the URL when you save unless you enable Skip URL payload test.

Authentication

Set Authentication on the connection to attach credentials to every request. All credentials are encrypted at rest.

None

No authentication headers are added. Use this when the endpoint is secured by other means such as an allowlisted IP range or a token baked into the URL path.

Basic Auth

Meshes sends an Authorization: Basic <base64> header built from the Username and Password you provide.

Bearer Token

Meshes sends an Authorization: Bearer <token> header with the Bearer Token you provide.

Custom Auth Header

Meshes sends a header with the Header Name and Header Value you provide, such as X-API-Key: sk-abc123. Use this for endpoints that expect a non-standard auth header.

Custom headers

You can add up to five static headers to every request. Custom headers are useful for routing keys, tenant identifiers, or any metadata your endpoint expects.

Reserved header names (Content-Type, Content-Length, Host, Transfer-Encoding) cannot be overridden. If a custom header name conflicts with an authentication header, the authentication header takes precedence.

Payload format

Wrapped (default)

Meshes sends the full event envelope as the request body:

{
  "uuid": "evt_123",
  "event": "user.signup",
  "resource": "user",
  "resource_id": "usr_2048",
  "payload": {
    "email": "test@example.com",
    "plan": "pro"
  },
  "time_created": 1711929600000,
  "time_sent": 1711929600500
}

Raw

Meshes sends only the payload object as the request body:

{
  "email": "test@example.com",
  "plan": "pro"
}

Event metadata that would otherwise appear in the envelope is promoted to HTTP headers so your endpoint can still access it:

Raw mode is useful when the receiving system expects a flat payload shape and cannot unwrap a Meshes envelope.

Payload signing (HMAC)

Enable HMAC signing so the receiver can verify that the request body was sent by Meshes and has not been tampered with. Signing is independent of authentication — a connection can use both.

Set Payload Signing (HMAC) to HMAC-SHA256 or HMAC-SHA512. When enabled, provide a Signing Secret. The secret is encrypted at rest and never returned in plaintext after it is saved.

For each request, Meshes computes the HMAC digest of the serialized request body using your secret and attaches the result in the Signature Header (default X-Meshes-Signature).

Verifying signatures

Your endpoint should recompute the HMAC from the raw request body and compare it to the header value. Example in Node.js:

import crypto from 'node:crypto';

function verifySignature(body, secret, receivedSignature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSignature)
  );
}

Signing options

The signature is always computed from the exact bytes Meshes sends as the request body, whether the payload format is wrapped or raw.

HTTP method

Choose POST, PUT, or PATCH on the connection. The default is POST. All methods send the same JSON body and headers — only the HTTP verb changes.

Header precedence

When multiple header sources overlap, Meshes applies this priority order (highest wins):

1. HMAC signature header — cannot be overridden
2. Metadata headers — X-Meshes-* headers in raw mode
3. Authentication header — Authorization or custom auth header
4. Custom static headers — your manually-added headers
5. Default headers — Content-Type: application/json, Accept, User-Agent

Create a rule

1. Open Rules and click New Rule.
2. Select the event type that should trigger the webhook, such as user.signup or lesson.completed.
3. Select the resource type for that event.
4. Choose your webhook connection.
5. Select Send Webhook.
6. Save the rule.

Webhook rules do not require action data or destination field mapping. Meshes delivers the event payload as configured on the connection.

Send a test event

Use Send Test Event on the rule to verify your endpoint accepts the request.

{
  "email": "test@example.com",
  "plan": "pro"
}

The test request includes the same authentication headers, custom headers, HMAC signature, HTTP method, and payload format configured on the connection.

Review results

After the event runs, open Events and inspect the webhook delivery details. Meshes shows whether the rule completed, what endpoint was called, the HTTP status returned, and any retries or failures.

Notes

• Webhook URLs must be secure https:// endpoints.
• Meshes treats 2xx and 3xx responses as successful delivery.
• A 410 Gone response automatically deactivates the rule.
• All credentials and signing secrets are encrypted at rest.
• Webhook rules do not use live action data such as lists, tags, or templates.