Webhook de eventos de Stripe

POST

/billing/webhook

curl --request POST \
  --url https://api.dev.lade.com.mx/billing/webhook \
  --header 'Content-Type: application/json' \
  --data '{ "id": "evt_1AbCDeFGhIJKlmn", "type": "checkout.session.completed", "data": { "object": { "mode": "subscription", "customer": "cus_AbCDeFGhIJKlmn", "subscription": "sub_1AbCDeFGhIJKlmn", "metadata": { "teamId": "550e8400-e29b-41d4-a716-446655440000", "planName": "STARTER" } } } }'

• Development environment (dominio custom)
• QA environment
• Production environment
• Development environment (legacy — execute-api URL directo)

Recibido directamente por Stripe (no requiere Cognito), verificado con la firma del header Stripe-Signature. Procesa checkout.session.completed (activa plan o agrega viajes de un paquete), customer.subscription.updated (sincroniza status/periodo), customer.subscription.deleted (regresa a FREE_TRIAL) e invoice.payment_failed (marca past_due). Deduplica eventos repetidos en memoria por contenedor Lambda. Errores no fatales al procesar un evento conocido devuelven 200 igualmente para que Stripe no reintente indefinidamente.

Request Body^required

Media typeapplication/json

Evento de Stripe (Event object)

object

Example

{
  "id": "evt_1AbCDeFGhIJKlmn",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "mode": "subscription",
      "customer": "cus_AbCDeFGhIJKlmn",
      "subscription": "sub_1AbCDeFGhIJKlmn",
      "metadata": {
        "teamId": "550e8400-e29b-41d4-a716-446655440000",
        "planName": "STARTER"
      }
    }
  }
}

Responses

200

Evento procesado (o ignorado/duplicado)

Media typeapplication/json

object

received

boolean

duplicate

boolean

warning

string

Example

{
  "received": true
}

400

Solicitud inválida

Media typeapplication/json

object

error

required

string

message

string

field

string

Example

{
  "error": "Validation failed",
  "field": "email",
  "message": "Invalid email format"
}