GUIDES

Webhooks

When a conversion ends, we POST an event to your server, signed with your endpoint's secret. Your server answers 2xx, then does the work.

Add an endpoint

On Developers, Webhooks, add your server's public https address and pick the events. Its signing secret (whsec_…) is shown once. Up to 10 endpoints per mode; test endpoints are free, live ones come with Pro.

The events

conversion.completed
conversion.failed
conversion.expired

The body is { object, id, type, timestamp, livemode, data }, and data is the conversion exactly as GET /v1/conversions/{id} answers it. Every field.

Verify every event

import { verifyWebhook } from "@vecsnap/sdk";

// rawBody: the request's body as text, before any JSON parsing
const event = await verifyWebhook(rawBody, request.headers, process.env.VECSNAP_WEBHOOK_SECRET);
if (event.type === "conversion.completed") {
  // dedupe on event.id: an event may arrive more than once
}

We sign by the Standard Webhooks scheme, so any of its libraries verifies us too: webhook-id, webhook-timestamp, webhook-signature.

Retries

An answer other than 2xx, or none in 15 seconds, is tried again about 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours after the first. A redirect is never followed. An endpoint that fails for 3 days, or answers 410, is turned off and shown so on its page; turn it back on when it works.

Test it

Send an example from the endpoint's card: a signed event carrying an example conversion, sent at once, the answer shown. Or convert with a test key: its events are real and free.