Skip to main content

​
Integrations guide

Notifizz ingests events from external sources via dedicated webhook endpoints. This guide walks through setting up each connector — Segment, Stripe, HubSpot, Intercom — from “zero” to “campaign fires from a provider event”. The exact wire format per provider is in connector webhooks reference. This page is task-oriented; jump there when you need the headers and HMAC formulas.

​
TL;DR

  • Each provider has a dedicated POST /v1/webhooks/{provider}/:sourceId endpoint.
  • The dashboard mints a sourceId and verificationSecret per source.
  • Configure the webhook on the provider side with the URL + secret.
  • Notifizz verifies the signature, maps the provider event to the Notifizz event grammar, and feeds it into the same pipeline as client.track() calls.

​
Common flow

The setup is the same shape for every provider:
1

Create a source in the dashboard

Pick the provider, name the source. The dashboard mints a sourceId and a verificationSecret. Both are needed in the next step.
2

Configure the webhook on the provider

Each provider has its own admin UI; the URL pattern is https://eu.api.notifizz.com/v1/webhooks/{provider}/<sourceId>. The secret goes into the provider’s “shared secret” / “signing secret” / “client secret” field — the exact name varies.
3

Test delivery

Most providers expose a “send test event” or “trigger sample” button. Use it; check the dashboard delivery history for the source. A successful test shows the raw payload + the mapped event.
4

Map provider events to Notifizz events

Each connector ships a default mapping that translates provider event types into the Notifizz grammar (e.g. Stripe’s invoice.payment_succeeded → stripe.invoice.paid). The dashboard exposes a UI for renaming and for marking unmapped types as “ignored”.
5

Wire campaigns

Mapped events behave exactly like client.track() events — campaigns key on the mapped name. Create a campaign listening on stripe.invoice.paid and trigger it from any Stripe webhook delivery.

​
Per-provider setup

​
Segment

1

Add a Segment source in Notifizz

Dashboard → Sources → Add → Segment. Note the URL and the verificationSecret.
2

Configure Segment

In Segment: Destinations → Webhooks → Create. Paste the Notifizz URL. In the destination’s settings, find “Shared Secret” and paste the verificationSecret.
3

Map your Segment events

Segment events arrive as track, identify, page, screen, or group. The mapper translates them — the most common pattern is track events keep their event name, others get a segment.identify / segment.page prefix. Customise via the dashboard’s mapping UI.
Signature scheme: header x-signature, value is hex(HMAC-SHA1(verificationSecret, rawBody)).

​
Stripe

1

Add a Stripe source in Notifizz

Dashboard → Sources → Add → Stripe. Note the URL.
2

Add a webhook endpoint in Stripe

Stripe Dashboard → Webhooks → Add endpoint. Paste the Notifizz URL. Pick the events you care about (or “all events” for low-volume accounts). Stripe shows a “Signing secret” — copy it and paste into the Notifizz source’s verificationSecret field.
3

Map Stripe events

Stripe event types use dotted notation already (invoice.paid, customer.subscription.updated). The mapper prefixes them with stripe. so they don’t collide with your own events.
Signature scheme: header stripe-signature with Stripe’s multi-element format (t=<ts>,v1=<sig>). Notifizz delegates to Stripe’s official verifier — the same logic as Webhook.constructEvent in the Stripe SDK.

​
HubSpot

1

Add a HubSpot source in Notifizz

Dashboard → Sources → Add → HubSpot. Note the URL.
2

Set up the HubSpot app webhook

HubSpot → Settings → Integrations → Apps → Webhooks → Create subscription. Paste the URL. Use the app’s Client Secret as the Notifizz verificationSecret.
3

Subscribe to events

HubSpot subscriptions are object-based (contact.creation, deal.propertyChange, …). The mapper produces hubspot.contact.created, hubspot.deal.updated, etc.
Signature scheme: header x-hubspot-signature-v2 (with x-hubspot-signature fallback), value is hex(HMAC-SHA256(clientSecret, rawBody)).

​
Intercom

1

Add an Intercom source in Notifizz

Dashboard → Sources → Add → Intercom. Note the URL.
2

Configure the Intercom webhook

Intercom → Settings → Webhooks → New Webhook. Paste the URL. Intercom shows a “Hub Secret” — copy it and paste into the Notifizz source’s verificationSecret.
3

Subscribe to topics

Intercom topics are conversation-centric (conversation.user.replied, contact.created, …). The mapper translates them to intercom.conversation.replied, intercom.contact.created, etc.
Signature scheme: header x-hub-signature, value is sha1=<hex(HMAC-SHA1(verificationSecret, rawBody))> — the same GitHub-style scheme. Note the sha1= prefix.

​
Debugging signature failures

The dashboard delivery history flags signature failures with a 401 entry. The most common causes:
SymptomCauseFix
401 on every deliveryWrong verificationSecretRe-copy from the provider — most providers regenerate the secret if you click “Show” then leave; copy fresh.
401 sporadicStripe timestamp driftNTP your Notifizz region (rare — Stripe’s tolerance is generous).
401 from a specific event typeProvider sent a non-JSON or pre-parsed bodyNotifizz expects raw JSON; if the provider unfortunately re-serialised, the byte mismatch breaks HMAC. Open a support ticket.
404 sourceIdWrong URLDouble-check the path — the sourceId must match the dashboard. Easy to mis-paste between environments.

​
Mapping events

Each connector ships a default mapping out of the box. The dashboard’s mapping UI exposes:
  • The list of provider event types observed in delivery history.
  • The mapped Notifizz event name (editable).
  • An “ignore” toggle for events you don’t want propagated.
Renames take effect immediately for new deliveries. Past deliveries keep their original mapping (they’re stored on the workflow instance for traceability).

​
FAQ

Both fail with 401, but for different reasons. Wrong sourceId produces a 404. Wrong secret produces 401 + signature failure in the log. The dashboard delivery history distinguishes the two — read the entry’s reason field.
By default the mapper produces stripe.customer.subscription.updated. Rename it to whatever your campaigns key on (subscription.updated, billing.subscription_changed, …). Naming consistency with your direct client.track() events makes campaigns easier to wire.
Mark them as “ignored” in the dashboard mapping UI. Notifizz still verifies the signature (so the provider sees 200 and stops retrying), but the event isn’t enqueued for campaigns.
Pause the source from its detail page in the dashboard. Pause persists across deploys. Webhook deliveries still arrive (the provider sees 200), but Notifizz drops them.
The connector uses the provider’s event id as the idempotencyKey. A retried delivery from Stripe short-circuits with { duplicate: true }. Genuinely identical events from your end (e.g. user clicks twice) have different event ids and are not deduped.
Yes — each source has its own sourceId + verificationSecret. You can have, say, two Stripe accounts (production + sandbox) wired to the same Notifizz environment; campaigns can match on event content if they need to differentiate.

​
See also

Connector webhooks reference

Wire format, headers, signature formulas.

Events

The grammar mapped events follow.

Campaigns

What runs after a mapped event matches.

Event Tracking

The native event format connectors normalise to.