API ReferenceWebhooks
Create a webhook endpoint
Registers a new URL to receive webhook events. Bag will send POST requests to this URL whenever the subscribed events occur.
The response includes a secret for verifying webhook signatures. This
secret is shown only once — store it securely. All webhook payloads are
signed with HMAC-SHA256 using this secret.
If no events array is provided, the endpoint subscribes to all event types.
Authorization
privy AuthorizationBearer <token>
Privy JWT authentication for dashboard and management endpoints. This is used internally by the Bag Dashboard and is not intended for direct API integrations. Use API keys instead.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.justusebag.xyz/api/webhooks" \ -H "Content-Type: application/json" \ -d '{ "url": "https://api.example.com/webhooks/bag", "events": [ "payment.completed", "payment.failed" ] }'{
"status": "success",
"data": {
"id": "f6a7b8c9-d0e1-4f2a-3b4c-5d6e7f8a9b0c",
"url": "https://api.example.com/webhooks/bag",
"secret": "whsec_k7m2p9x4q8r1t6v3w5y0a2b4c6d8e0f1",
"events": [
"payment.completed",
"payment.failed"
],
"active": true
}
}{
"status": "error",
"message": "amount: Amount must be a positive number up to 999,999,999.99; network: Invalid enum value",
"code": "BAD_REQUEST"
}{
"status": "error",
"message": "Invalid or revoked API key",
"code": "UNAUTHORIZED",
"hint": "Include a valid API key in the Authorization header: Bearer bag_live_sk_..."
}{
"status": "error",
"message": "Too many requests. Please slow down.",
"retryAfter": 10
}