Webhooks
Signed, tenant-scoped HTTPS delivery for LocusVia product events.
Endpoint configuration#
Environment scoped
Each endpoint belongs to one tenant and one environment.
Explicit subscriptions
An endpoint receives only its selected event types.
Active state
Disabled endpoints do not receive or claim new deliveries.
Owner controls
Sensitive operations such as secret rotation and replay require elevated authorization.
Event catalog#
Subscribe to granular mobile journey and referral lifecycle events:
referral.attributed
Dispatched when an invitee clicks or deferred-resolves an active participant share link.
referral.converted
Dispatched when an attributed user completes an in-app goal (e.g. signup, first purchase).
referral.claim_created
Dispatched when a reward claim is idempotently recorded and evaluated for eligibility.
referral.claim_approved
Dispatched when an eligible reward claim is approved by automated policy or operator.
referral.claim_denied
Dispatched when a claim is rejected due to policy violations, self-referral, or claim caps.
referral.fraud_flagged
Dispatched when attestation checks or anti-abuse velocity limits detect anomalies.
Verify signatures#
Every delivery includes a timestamped HMAC-SHA256 signature. Reconstruct the signed input exactly, reject stale timestamps, compare signatures in constant time, and accept the current or still-valid previous secret during rotation.
signed = timestamp + "." + eventId + "." + rawBody
signature = HMAC-SHA256(secret, signed)Warning
Verify against the unmodified request body before parsing JSON.Delivery and retries#
Return a success status promptly after durable acceptance. Retryable failures use exponential backoff; terminal responses and exhausted retries remain visible for diagnosis and authorized replay.
Delivery order is not guaranteed across endpoints. Consumers should use the event identifier for idempotency.
Replay and rotation#
Authorized owners can replay a failed delivery without creating a new product event. Secret rotation keeps the previous secret valid for a bounded overlap so in-flight deliveries can still be verified.
Network safety#
Webhook destinations must use HTTPS and resolve to eligible public addresses. Redirects and address changes are revalidated to prevent delivery to private or restricted networks.