Skip to main content

​
Webhooks: closing the loop

Signed events keep your systems in step with what customers do in their wallets. Three event types exist today: PASS_CREATED, PASS_STATUS_CHANGED, and TRANSACTION_CREATED. Each is routed to your handler via the X-Stell-Event header. Create subscriptions in the portal. The full delivery contract, covering headers, payloads, and signature verification with code samples, is documented in webhook deliveries. The integration-level takeaways:
  • Verify, then acknowledge fast. Check the signature, return a 2xx immediately, and process the event asynchronously.
  • Delivery is at-least-once. Deduplicate on X-Stell-Delivery-Id so a retried delivery is never processed twice.
  • Failures are retried, persistently. Each delivery cycle makes up to 3 attempts with short backoff, and failed events are re-driven in repeated cycles for up to roughly 24 hours. An endpoint recovering from an outage will see many deliveries of the same event. The dedupe rule above absorbs exactly that.
  • No lookup needed. PASS_CREATED and PASS_STATUS_CHANGED payloads carry your externalId, so the write-back to your customer record takes no extra call.
  • Subscribe to what you act on. If your backend already knows it issued a pass, because it made the call, PASS_CREATED tells you nothing new. It earns its place when passes are also issued outside your integration, through the portal or an enrollment page.

​
The pass lifecycle

Six statuses, delivered to you through the same webhook. Handle all six in your write-back logic: Two transitions dominate: PREACTIVE → ACTIVE when a customer adds the pass, and ACTIVE → INACTIVE when one removes it. Reflect both in your CRM so campaigns and support see wallet reality. For the merchant-facing view of the same lifecycle, see pass lifecycle.

​
Go-live checklist

  • The API key is stored and used server-side only. It never reaches a browser, app, or client-side code.
  • Add to Wallet is idempotent: every create is preceded by a lookup on programId + externalId.
  • Wallet links are requested at click time and never cached, stored, or emailed as durable URLs.
  • Your webhook endpoint verifies X-Stell-Signature, responds 2xx quickly, and processes events asynchronously.
  • Deliveries are deduplicated on X-Stell-Delivery-Id.
  • All six pass statuses are handled in your write-back logic.
  • The externalId mapping is tested end to end: create → add → webhook → write-back lands on the right customer record.
  • The in-store payload, whether a template placeholder or the API payload field, points at the identifier your POS resolves, verified on a test pass.
  • NFC only: your terminal fleet supports Apple VAS / Google Smart Tap with keys provisioned (confirmed with your terminal vendor), and an end-to-end tap is verified at a pilot store: tap → customer identifier at the POS → points accrual → pass update on the device.
Questions along the way? Contact support.