Aplauso uses a Stripe webhook endpoint to receive real-time payment events from Stripe and finalize tip transactions. This endpoint is managed by Aplauso and does not require configuration by property admins.
This article is relevant for developers who are testing locally or building custom payment flows that interact with the tip lifecycle.
Webhook Endpoint
POST /v2/webhooks/stripe
Authentication: No bearer token - authenticated via Stripe's webhook signature header (Stripe-Signature).
Handled Events
| Stripe Event | Action |
|---|---|
payment_intent.succeeded | Updates tip status to Paid (20); creates dividend records for all recipients |
payment_intent.payment_failed | Marks tip as payment failed |
payment_intent.canceled | Cancels tip if still in pending state |
charge.succeeded | Supplementary payment confirmation |
charge.failed | Records charge failure |
charge.refunded | Reverses dividend from employee wallet |
charge.dispute.created | Records chargeback/dispute |
Aplauso responds with {"received": true} and HTTP 200 to Stripe for all events, including ones it does not handle. This is required so Stripe does not retry unnecessarily.
Idempotency
The webhook handler is idempotent. If Stripe delivers the same event more than once (which Stripe does for reliability), the handler detects the tip was already processed and returns success without creating duplicate dividends.
Tip Metadata
Tips that flow through the kiosk include a tipId in the Stripe Payment Intent metadata. The webhook reads this metadata to find the matching Aplauso tip record:
{
"metadata": {
"tipId": "tip_xxxxxxxxxxx"
}
}
If your custom integration creates Payment Intents manually (for a custom payment UI), include tipId in the metadata to ensure the webhook processes the tip correctly.
Testing Webhooks Locally
Use the Stripe CLI to forward webhook events to your local Firebase emulator:
stripe listen --forward-to http://localhost:5001/aplauso-f0501/us-central1/api/v2/webhooks/stripe
Then trigger a test event:
stripe trigger payment_intent.succeeded
Or use the Stripe Dashboard > Developers > Webhooks > Send test event.
Locally, use the test Stripe webhook secret from your .env file:
STRIPE_WEBHOOK_SECRET=whsec_test_...
Checking Event Results
After a webhook processes, verify the tip record was updated:
GET /v2/tips?employeeId=abc123&environment=sandbox
Tips processed by the webhook will show status: 20 and have dividend records available at:
GET /v2/dividends?tipId=tip_xxxxxxxxxxx&environment=sandbox