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>"
    }
  ]
}
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