---
title: "Inbound Stripe event (server-to-server)"
method: POST
path: "stripeEvent"
---

# Inbound Stripe event (server-to-server)

`POST stripeEvent` (webhook)

Stripe posts billing events to https://rrmacademy.org/api/stripe-webhook . The handler verifies the `Stripe-Signature` header (HMAC-SHA256 over the raw request body, prefixed with a timestamp, per https://docs.stripe.com/webhooks/signatures) before processing. Requests with a missing or invalid signature are rejected with 400. The handler is idempotent: replayed events with the same `id` short-circuit on a dedup KV record. Accepted event types: `checkout.session.completed`, `checkout.session.expired`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed`, `charge.refunded`. This is the only inbound webhook surface; rrmacademy.org does not currently emit outbound webhooks to consumers.

## Headers

- `Stripe-Signature` string, required

## Payload

- StripeWebhookEvent: Subset of the Stripe Event object delivered to /api/stripe-webhook. Full schema: https://docs.stripe.com/api/events/object.
  - `id` string, required
  - `type` string, required: Stripe event type. Accepted types: checkout.session.completed, checkout.session.expired, customer.subscription.updated, customer.subscription.deleted, invoice.payment_failed, charge.refunded.
  - `data` object, required: Event payload. Shape varies by event type.
  - `livemode` boolean
  - `created` integer

## Acknowledgement `200`

Event accepted (verified, dispatched to the matching handler, or idempotently skipped).

## Other responses

- `400`: Missing or malformed `Stripe-Signature` header, malformed JSON body, or signature failed HMAC verification.
- `500`: Internal error while processing the event. Stripe will retry per its retry policy.

---

[API](https://skmtc.dev/rrmacademy/apis/rrm-academy-agent-api.md) · [All operations](https://skmtc.dev/rrmacademy/apis/rrm-academy-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/rrmacademy/apis/rrm-academy-agent-api/revisions/0e3589a38b0c?raw)