Skip to main content
POST
/
api
/
v1
/
payments
/
stripe
/
webhooks
/
{project_id}
/
{mode}
Handle Stripe Webhook
curl --request POST \
  --url https://api.devkit4ai.com/api/v1/payments/stripe/webhooks/{project_id}/{mode}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://devkit4ai.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Receive and process webhook events from Stripe. This endpoint should be configured in your Stripe Dashboard to receive events for checkout completions, subscription changes, and payment updates.

​
Authentication

This endpoint does NOT use Bearer token authentication. Instead, it validates requests using the Stripe webhook signature.

​
Path Parameters

​
project_id
string (UUID)
required
The unique identifier of the project
​
mode
string
required
Webhook mode: test or live

​
Headers

​
stripe-signature
string
required
Stripe signature header for webhook verification

​
Request Body

Stripe sends event payloads as JSON. The body contains the event object with type and data.

​
Response

Returns 200 OK on successful processing.

​
Webhook URL Format

https://api.devkit4ai.com/api/v1/payments/stripe/webhooks/{project_id}/{mode}
ModeDescription
testFor test mode webhooks (development)
liveFor live mode webhooks (production)
Use the Get Webhook URLs endpoint to get the correct URLs for your project.

​
Supported Events

The Cloud API processes these Stripe events:
EventAction
checkout.session.completedCreates subscription and customer records
customer.subscription.createdRecords new subscription
customer.subscription.updatedUpdates subscription status/plan
customer.subscription.deletedMarks subscription as canceled
invoice.paidRecords successful payment
invoice.payment_failedMarks subscription as past_due

​
Event Processing Flow

​
Webhook Verification

All webhooks are verified using the signing secret configured in your Stripe settings:
Security: Always use HTTPS for webhook endpoints. Never log or expose the webhook signing secret.

​
Configuring Webhooks

1

Get Webhook URLs

Call Get Webhook URLs to get your project’s webhook endpoints.
2

Create Endpoint in Stripe

Go to Developers > Webhooks in Stripe Dashboard and click Add endpoint.
3

Configure Events

Select the events to receive:
checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.paid
invoice.payment_failed
4

Save Webhook Secret

Copy the signing secret and save it using Update Stripe Config.

​
Local Development

Use Stripe CLI to forward webhooks to your local development server: 
# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login to Stripe
stripe login

# Forward webhooks to local backend
stripe listen --forward-to localhost:8000/api/v1/payments/stripe/webhooks/{project_id}/test

# The CLI will display a webhook secret - use this for local testing

​
Event Payload Example

{
  "id": "evt_1ABC123def456",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "cs_test_a1b2c3d4",
      "customer": "cus_XYZ789",
      "subscription": "sub_ABC123",
      "metadata": {
        "user_id": "990e8400-e29b-41d4-a716-446655440000"
      }
    }
  }
}

​
Error Responses

StatusDescription
400Invalid signature or malformed payload
404Project not found or Stripe not configured
500Internal error processing event

​
Retry Behavior

Stripe retries failed webhooks for up to 3 days with exponential backoff. Return 200 OK quickly to acknowledge receipt - process data asynchronously if needed.

Get Webhook URLs

Get your webhook endpoint URLs

Update Stripe Config

Save webhook signing secret

List Project Subscriptions

View created subscriptions

Path Parameters

​
project_id
string<uuid>
required
​
mode
string
required

Response

Successful Response