Skip to main content
A subscription ties a URL on your server to a set of event types you want to receive. You can have multiple subscriptions per location (one for billing events to your billing system, another for contact events to your CRM, etc.) and each one signs deliveries with its own HMAC secret. All subscription management happens in the FPT admin at Settings → Webhook Endpoints. We don’t yet expose a public REST API for this — it’s coming, but for v1.1 it’s UI-only.

​
What’s in a subscription

FieldDescription
URLWhere we POST events. Must be HTTPS. We reject private/RFC1918 ranges and IPs in non-routable spaces.
Event typesWhich events to deliver to this URL. You can pick any combination — contact.* events, future event families, etc.
ScopeEither location-level (events only from one location) or organization-level (events from every location in your org). The default depends on your admin role.
PII categoriesWhat categories of personal data are included in payloads. Defaults match the most common partner use case; tighten if your contract requires it.
Signing secretThe HMAC secret used to sign every delivery from this subscription. Revealed once when generated; rotatable.
Statusactive, paused, disabled. See delivery semantics for when these flip automatically.

​
Scope: location vs organization

  • Location-scoped subscription: deliveries include only events whose locationId matches your single subscribed location.
  • Organization-scoped subscription: deliveries include events from every location under your organization. The locationId in the envelope tells you which one.
Pick organization scope if your integration spans multiple locations under a parent (franchise / corporate account). Pick location scope if you’re integrating per-location and want isolation.
You can only create organization-scoped subscriptions if you have organization-admin access. Location admins can only create location-scoped subscriptions.

​
Creating a subscription

1

Settings → Webhook Endpoints

Navigate from the FPT admin sidebar.
2

Add Endpoint

Opens a dialog with the URL + event-types + PII fields.
3

Save

The subscription is active immediately. New events from the next change onward are delivered.
4

Generate Key

Click on your new endpoint’s row. The dialog shows a one-time signing secret — copy it now and store in your secrets manager. You can’t view it again; you can only rotate.

​
Editing a subscription

You can change:
  • URL — takes effect immediately for new deliveries (in-flight deliveries keep their existing target)
  • Event types — adding new ones means you’ll start receiving them on the next change; removing them stops deliveries of that type
  • PII categories — affects payload projection for new deliveries
You can’t change scope (location vs organization) — that requires deleting and recreating.

​
Rotating the signing secret

See the key rotation section in Signature verification for the full procedure. Summary:
1

Click Rotate Key on the subscription row

Dialog reveals the new secret one time.
2

Deploy the new secret to your endpoint

Update your FPT_WEBHOOK_SECRET env var, restart your service.
3

Verify a real event lands and verifies OK

Edit a contact, watch the next delivery.
Rotation invalidates the old secret immediately. There’s no grace period where both work. Plan your rotations during low-traffic windows or use the test-event flow to verify before broadcasting.

​
Pausing and re-activating

  • A paused subscription stops receiving new events but isn’t deleted. The configuration is preserved.
  • A subscription that fails for 24 hours straight automatically transitions to disabled — see delivery semantics. Re-enable from the same admin page.
  • Disabled subscriptions don’t catch up on events missed while disabled. Re-enabling resumes delivery for new events going forward.

​
Deletion

Deleting a subscription is permanent. Pending retries are dropped. The signing secret stops being valid. If you want to temporarily stop receiving events without losing the subscription, pause it instead.

​
Coming soon

v1.2 will ship a public REST API for subscription management — programmatically create / update / rotate / delete subscriptions, useful for partners onboarding new customers programmatically.v1.3 plans a webhook-management partner portal hosted at this docs site, so partners can see delivery history, retry failed deliveries, and inspect raw payloads without needing an FPT admin login.