Connect webhooks and Klaviyo

Use Settings → Emails to control buyer-facing email and Settings → Integrations to connect your own systems. Webhooks and Klaviyo are independent: an outage or unavailable OAuth connection in one does not stop buyer email or the other integration.

What you'll accomplish

• Set the reply-to address and customize registration or recall email templates.
• Create and verify an HTTPS webhook endpoint.
• Validate Serial Trail signatures, including secret rotation.
• Connect Klaviyo and choose consent-gated registration events.
• Inspect and replay failed deliveries.

Requirements

• A Warranty or Ops plan.
• The Registration feature for registration email templates, or Recall for recall templates.
• A public HTTPS webhook endpoint that returns within 10 seconds.
• A Klaviyo account with permission to authorize an OAuth app.

Warranty supports five product webhook endpoints. Ops supports twenty.

Configure buyer email

1. Open Settings → Emails → Sender & suppression.
2. Enter the inbox that should receive buyer replies, then select Save reply-to.
3. Confirm the read-only sender preview shows your shop name followed by “via Serial Trail.”
4. Open Templates, choose a category, and edit the subject or limited-markdown body.
5. Keep every required safety variable shown by the editor. Unknown variables and unsafe links are rejected.
6. Select Preview, then Send test. Reset removes your override and restores the code-owned default.

The activity tab shows the latest 100 buyer messages. The suppression list blocks matching registration and recall email; removing a suppression is audit logged.

Create a webhook

1. Open Settings → Integrations → Webhooks.
2. Enter a name and a public HTTPS URL.
3. Optionally add up to four custom X-* headers, one Name: value pair per line.
4. Select one or more topics and choose Create webhook.
5. Copy the signing secret immediately. It is not shown on later reads.
6. Choose Test. The endpoint becomes active only after a successful 2xx test response.

The destination URL is immutable so changing a receiver cannot silently reuse an active secret or bypass activation. Create and test a new endpoint, switch your receiver, then disable the old endpoint. Name, topics, and replacement custom headers remain editable by API.

Product subscriptions expose exactly these v1 topics:

• registration.created
• registration.approved
• registration.rejected
• registration.transferred
• recall.case.activated
• recall.case.closed
• recall.wave.completed

Registration payloads may contain owner_email. Recall payloads do not contain owner contact details.

Verify webhook signatures

Every delivery includes X-SerialTrail-Timestamp, X-SerialTrail-Delivery-Id, and X-SerialTrail-Signature. Reject timestamps more than five minutes from your server clock, compute HMAC-SHA256 over <timestamp>.<raw request body>, and compare in constant time.

function serialTrailSignatureIsValid(
    string $rawBody,
    array $headers,
    string $signingSecret,
): bool {
    $timestamp = (string) ($headers['X-SerialTrail-Timestamp'] ?? '');
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac(
        'sha256',
        $timestamp . '.' . $rawBody,
        $signingSecret,
    );
    $provided = array_filter([
        $headers['X-SerialTrail-Signature'] ?? null,
        $headers['X-SerialTrail-Signature-Previous'] ?? null,
    ], 'is_string');

    foreach ($provided as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }

    return false;
}

Use the exact raw bytes received, before JSON decoding. Header lookup may need normalization for your framework.

When you rotate the secret, the main signature uses the new secret and X-SerialTrail-Signature-Previous uses the old secret for 48 hours. Deploy the new secret during that window. The previous-signature header disappears when the grace period ends.

Delivery outcomes and replay

• A 2xx response succeeds.
• A 410 response permanently disables the endpoint.
• Other 3xx and 4xx responses are dead-lettered without retry.
• Network errors and 5xx responses retry on the managed ladder from 30 seconds to 12 hours.
• Fifty consecutive failures auto-pause the subscription.

Open Deliveries to see status and error details. After correcting the receiver, replay a dead-lettered delivery. Treat delivery_id and the envelope idempotency_key as deduplication keys in your receiver.

Connect Klaviyo

1. Open Settings → Integrations → Klaviyo.
2. Select Connect Klaviyo and approve the OAuth request.
3. Enable Product registered, Registration approved, or both.
4. Select Save events.
5. Create a test registration with marketing consent and verify the corresponding metric in Klaviyo.

The stable Klaviyo metric names are Serial Trail Product Registered and Serial Trail Registration Approved. A registration without marketing consent is not sent. There is no send-all override, and recall or safety events are never sent to Klaviyo.

If a dispatch exhausts retries, it appears under Events needing attention. Correct the provider issue, then select Replay. Disconnecting revokes the installed app in Klaviyo, deletes the stored OAuth credentials, and stops future sends. If Klaviyo cannot confirm the revocation, Serial Trail keeps the connection unchanged and asks you to retry instead of reporting a partial disconnect. Disconnect does not delete data Klaviyo already accepted.

What success looks like

• A real buyer message uses the saved reply-to and customized template.
• A test webhook activates the endpoint, and your receiver verifies the raw-body signature.
• Both the old and new secret verify during rotation, then only the new secret verifies.
• A consented registration creates the selected Klaviyo metric exactly once.
• A non-consented registration creates no Klaviyo profile or event.

Troubleshooting

The webhook stays pending

Symptom: The endpoint never becomes active.

Likely cause: The test did not return 2xx within 10 seconds, the certificate is invalid, or DNS resolves to a private or reserved address.

Fix: Use a public HTTPS endpoint, correct its certificate and response, then run Test again.

Confirm: The endpoint status changes to Active.

The signature does not match

Symptom: Your receiver rejects a valid delivery.

Likely cause: It signs parsed JSON instead of the raw body, uses the wrong timestamp, or has not handled the rotation header.

Fix: Preserve raw request bytes, use the timestamp header in the signed string, and check both signature headers with hash_equals.

Confirm: The documented verifier returns true while the timestamp is within five minutes.

Connect Klaviyo is unavailable

Symptom: The connect button is disabled or OAuth returns an integration error.

Likely cause: The Klaviyo partner app credentials or redirect registration are temporarily unavailable.

Fix: Contact support with the time of the attempt. Continue using templates and webhooks; they are not dependent on Klaviyo OAuth.

Confirm: The Klaviyo card shows the connected account and event toggles.

Billing and responsibility

Serial Trail includes these surfaces in Warranty and Ops; there is no per-delivery Serial Trail fee. Your own webhook infrastructure and Klaviyo plan may have separate costs and limits. You are responsible for receiver security, lawful marketing consent, downstream retention, and honoring privacy requests in systems that already received data.