Usermaven
Dark mode

Connect a custom webhook

What you'll build: a private endpoint that turns JSON or form data from any service into Usermaven events. Time: about 10 minutes. You'll need: a tool that can send webhooks (or a developer who can add one HTTP call), and permission to create integrations in Usermaven.

The generic webhook source is the catch-all: if your tool isn't in the catalog but can send an HTTP request, it can send events to Usermaven. CRMs, e-signature tools, support desks, your own backend, anything.

Step 1: Create the source

  1. In Usermaven, go to Events → Event sources and click New event source.

  2. Pick Webhook from the catalog.

  3. Usermaven immediately starts listening for the first incoming test event. If you don't have one yet, click Use bundled sample to continue configuring the source without waiting for a live request.

  4. Name the source after what it tracks (Contracts signed, not Webhook 3) and click Create webhook URL.

image.png

The URL is a password. Anyone who has it can send events to your workspace. Store it like a secret, never put it in public browser JavaScript, and if it's ever exposed, rotate it from the source's Settings tab — the old URL keeps working for 24 hours so nothing is lost mid-switch.

Step 2: Send or simulate a test event

Point your tool at the URL and trigger a test, or send one yourself:

curl -X POST "your-webhook-url" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "contract_signed",
    "email": "buyer@example.com",
    "user_id": "customer_123",
    "amount": 129.99,
    "currency": "USD",
    "external_id": "contract_789",
    "occurred_at": "2026-07-01T12:30:00Z"
  }'

Once Usermaven receives the first test event, it automatically opens the mapping step using the received payload. Test requests received while the source is a draft are recorded as samples only, nothing reaches your analytics until you activate.

What the endpoint accepts: a JSON object, an array of up to 100 JSON objects, or form-encoded data, up to 256 KB per request. Field names are entirely up to you, that's what mapping is for.

Step 3: Map the fields

Usermaven automatically detects the available fields and lets you map them into the following sections:

  • Identity, map at least one of Email, User ID, or Anonymous ID. If you send more than one, they're preserved together; User ID is authoritative, an email will never override it.

  • Event name, set a fixed name (recommended for predictable reporting) or map it from a payload field. One source can emit at most 25 distinct event names, so a fixed name is the tidy choice.

  • Revenue & currency, pick the transform that matches how your tool sends amounts: as-is, divided by 100 (for cent-based amounts), or strip symbols (for formatted values like $1,299.00).

  • External ID, map a stable record ID. Webhooks get retried; this is what turns a retry into a harmless duplicate instead of a double-counted conversion.

  • Filters, only record requests that match a condition (for example, status equals completed), so one noisy endpoint doesn't become noisy analytics.

Click Preview event to review the mapped event. If everything looks correct, click Save source, then Activate and open source.

image.png

Optional: verify your sender

If your sending service signs its requests with HMAC, turn on Sender verification in the source's Settings tab and share the generated secret with the sender. Usermaven will then reject any request that isn't properly signed, worth doing for anything revenue-related. Rotating the secret keeps the previous one valid for 24 hours so queued deliveries aren't dropped.

For developers: how the endpoint responds

If you're writing the sending code, three behaviors are worth knowing:

  • Every record gets its own result. Batches return per-record outcomes (accepted, rejected, duplicate, filtered, …) one bad record never poisons a batch.

  • Respect Retry-After. A 429 (rate limit or daily cap) or 503 tells you when to retry. Retry the whole request with the same External IDs, already-accepted records deduplicate cleanly.

  • A rejected record is a data problem, not a retry problem. If a record comes back accepted: false with a reason, fix the data or the mapping; re-sending it unchanged (or with a fresh External ID) won't help.

Delivery is at-least-once by design, which is exactly why the External ID matters.

Verify it's working

Send one real event and check the source's Event log for an Accepted delivery. Open the entry to see both the original data received and the exact event recorded. Then find it in Events activity, filtered by this source.


Was this article helpful?