Webhooks

Receive real-time notifications for booking events, payments, and voice calls

Overview

ETERA uses webhooks to notify your application of asynchronous events — payment confirmations, booking status changes, and voice call outcomes.

Payment Webhooks

Stripe payment lifecycle events

Voice AI Webhooks

Automated reservation call outcomes

Async Queue

AI Supervisor processing status


Webhook Types

The Payment service receives Stripe webhook events for payment lifecycle updates.

EndpointMethodDescription
/payment/webhookPOSTStripe event receiver

Stripe events include payment intent confirmations, refund updates, subscription changes, and invoice payments. See the Payment API reference for the full schema.

Verifying Stripe Signatures

1import Stripe from "stripe";
2
3const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
4const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;
5
6async function handleWebhook(req: Request) {
7 const body = await req.text();
8 const sig = req.headers.get("stripe-signature")!;
9
10 const event = stripe.webhooks.constructEvent(
11 body, sig, endpointSecret
12 );
13
14 switch (event.type) {
15 case "payment_intent.succeeded":
16 // Handle successful payment
17 break;
18 case "payment_intent.payment_failed":
19 // Handle failed payment
20 break;
21 }
22}

Webhook Security

Always verify webhook signatures before processing events. For Stripe webhooks, use the Stripe-Signature header with your webhook signing secret.


Best Practices

1

Return 200 quickly

Acknowledge the webhook before processing. Use a queue for heavy work to avoid timeouts.

2

Handle duplicates

Webhooks may be sent more than once. Use event IDs for idempotency to prevent duplicate processing.

3

Implement retry logic

If your endpoint returns a non-2xx status, the event will be retried with exponential backoff.

4

Log everything

Store raw webhook payloads for debugging and auditing. This is essential for troubleshooting payment issues.


Next Steps