Skip to main content

​
Connector webhooks reference

Notifizz ingests events from external sources via per-provider webhook endpoints. Each connector verifies the provider’s signature scheme, normalises the payload to the Notifizz event shape, and feeds it into the same pipeline as direct SDK track() calls.

​
TL;DR

  • Endpoint: POST /v1/webhooks/{provider}/:sourceId per provider.
  • Each provider has its own header name and HMAC scheme — Notifizz handles them all.
  • The connector’s verificationSecret is per-source and stored in the dashboard.
  • Once verified, the payload is mapped to a normalised event and pushed to the same queue as SDK calls.

​
Supported providers

ProviderEndpointHeaderAlgorithmBody
SegmentPOST /v1/webhooks/segment/:sourceIdx-signatureHMAC-SHA1 hexraw JSON
StripePOST /v1/webhooks/stripe/:sourceIdstripe-signatureStripe SDK verifierraw JSON
HubSpotPOST /v1/webhooks/hubspot/:sourceIdx-hubspot-signature-v2 (or x-hubspot-signature)HMAC-SHA256 hexraw JSON
IntercomPOST /v1/webhooks/intercom/:sourceIdx-hub-signaturesha1=<HMAC-SHA1 hex>raw JSON
Notifizz handles signature verification per provider, with Stripe’s multi-element format delegated to its official verifier semantics.

​
Setup flow

1

Add a source in the dashboard

Pick the provider, name the source. Notifizz mints a sourceId and a verificationSecret. The pair is what the webhook URL and the signature use.
2

Configure the webhook on the provider

Each provider has its own admin UI:
  • Segment — Destinations → Webhooks → paste https://eu.api.notifizz.com/v1/webhooks/segment/<sourceId>, paste the verificationSecret as the shared secret.
  • Stripe — Webhooks → Add endpoint → paste the URL, copy the Stripe signing secret back into the dashboard’s source.
  • HubSpot — Settings → Integrations → Webhooks → paste the URL, copy the app’s Client Secret back into the dashboard.
  • Intercom — Settings → Webhooks → paste the URL, copy the Hub Secret back into the dashboard.
3

Map provider events to Notifizz events

Each connector ships a default mapping that translates the provider’s event names into the Notifizz event grammar. The dashboard surfaces unmapped event types so you can wire them up explicitly.
4

Wire campaigns to the mapped events

From the campaign side, mapped events are first-class — your campaign listens on stripe.invoice.paid (or whatever name your mapper produces) the same way it listens on client.track() events.

​
Per-provider signature details

​
Segment

signature = hex(HMAC-SHA1(verificationSecret, rawBody))
Header: x-signature. Direct hex comparison. See.

​
Stripe

Stripe’s signature format includes a timestamp and an HMAC, separated by commas — t=<ts>,v1=<sig>. The Notifizz verifier delegates to Stripe’s SDK Webhook.constructEvent semantics via a dedicated port — no apiKey is required for verification; the secret alone is enough. Header: stripe-signature.

​
HubSpot

signature = hex(HMAC-SHA256(verificationSecret, rawBody))
Header: x-hubspot-signature-v2, with a x-hubspot-signature fallback. See.

​
Intercom

signature = "sha1=" + hex(HMAC-SHA1(verificationSecret, rawBody))
Header: x-hub-signature (the same scheme as GitHub-style webhooks — note the sha1= prefix). See.

​
Normalised event shape

After verification, each connector’s event-mapper produces a standard Notifizz event: 
{
  "eventName": "stripe.invoice.paid",
  "properties": { /* provider payload, normalised */ },
  "sdkSecretKey": "<resolved from sourceId>",
  "idempotencyKey": "<provider-event-id>"
}
The idempotencyKey is derived from the provider’s event id so re-deliveries from the provider naturally dedupe.

​
FAQ

Both produce a 401. Most common cause: the verificationSecret in the dashboard doesn’t match the one configured on the provider. Less common: the URL :sourceId segment is wrong (typo or wrong env). Check the request log — the failed verification is logged with which check failed.
The event was accepted (signature OK), but no campaign listens on the mapped event name. Either: (1) the connector’s mapping hasn’t named this event type yet (check the dashboard’s “unmapped events” view), or (2) no campaign is wired to the mapped name. The dashboard delivery history shows the event with a no-route entry.
The mapping happens in the connector. The dashboard exposes a UI for renaming mapped events without touching code — the rename takes effect immediately for new webhook deliveries.
Pause it from the source detail page in the dashboard. Pause persists across deploys. Webhook deliveries still arrive, but they’re rejected with a 200 + paused flag — the provider sees success and stops retrying, but Notifizz drops them.
The connector uses the provider’s event id as the idempotency key. A retried delivery from Segment short-circuits at the backend with { duplicate: true }. Genuinely identical events from your end (e.g. user clicks twice) are not deduped — they have different event ids.
Yes — each source has its own sourceId and verificationSecret. You can have, say, two Stripe accounts wired to the same Notifizz environment; campaigns can match on event content if they need to differentiate.

​
See also

Event Tracking

The native event format that connectors normalise to.

Integrations guide

Customer-facing setup walkthrough per provider.

Error catalogue

Webhook verification error codes.

How Notifizz works

Where connector events join the pipeline.