{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["img"]},"type":"markdown"},"seo":{"title":"Webhooks","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ChaChing Webhooks allow your system to receive ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["real-time notifications"]}," when events occur in your ChaChing account (e.g., customer updates, payments, subscriptions)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks are designed for clients using the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["public API"]},", which allows them to react to system changes without polling."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-webhooks-work","__idx":1},"children":["How Webhooks Work"]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"graph TD;\n A[\"Event occurs in ChaChing (e.g. invoice.paid)\"] --> B[\"Generate event notification\"];\n B --> C[\"Find active webhook destinations\"];\n C --> D[\"Send HTTP POST request to webhook endpoint\"];\n D --> E[\"Client processes request\"];\n E --> F{\"Response is HTTP 2xx?\"};\n\n F -- Yes --> G[\"Mark delivery as successful\"];\n F -- No --> H[\"Retry delivery (according to retry policy)\"];\n H --> I{\"Max retries reached?\"};\n\n I -- No --> D;\n I -- Yes --> J[\"Stop retries - Mark as failed\"];\n","diagramHtml":"

Yes

No

No

Yes

Event occurs in ChaChing (e.g. invoice.paid)

Generate event notification

Find active webhook destinations

Send HTTP POST request to webhook endpoint

Client processes request

Response is HTTP 2xx?

Mark delivery as successful

Retry delivery (according to retry policy)

Max retries reached?

Stop retries - Mark as failed

","diagramHtmlDark":"

Yes

No

No

Yes

Event occurs in ChaChing (e.g. invoice.paid)

Generate event notification

Find active webhook destinations

Send HTTP POST request to webhook endpoint

Client processes request

Response is HTTP 2xx?

Mark delivery as successful

Retry delivery (according to retry policy)

Max retries reached?

Stop retries - Mark as failed

"},"children":["graph TD;\n A[\"Event occurs in ChaChing (e.g. invoice.paid)\"] --> B[\"Generate event notification\"];\n B --> C[\"Find active webhook destinations\"];\n C --> D[\"Send HTTP POST request to webhook endpoint\"];\n D --> E[\"Client processes request\"];\n E --> F{\"Response is HTTP 2xx?\"};\n\n F -- Yes --> G[\"Mark delivery as successful\"];\n F -- No --> H[\"Retry delivery (according to retry policy)\"];\n H --> I{\"Max retries reached?\"};\n\n I -- No --> D;\n I -- Yes --> J[\"Stop retries - Mark as failed\"];\n"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An event occurs in ChaChing (e.g., customer details updated). For details related to the event types, refer to the section ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.notion.so/Webhook-API-326dc7fc0a9280d087a1fe916d21c46c?pvs=21"},"children":["Event Types"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ChaChing generates an event notification."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ChaChing identifies all ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["active webhook endpoints"]}," configured for the account."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["ChaChing sends the event with its payload as an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP POST request"]}," to each webhook endpoint."," ","Note: For payload details, refer to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Event Structure"]}," section."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your system receives and processes the event."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Your endpoint must return an HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," response:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," response is returned, the delivery is marked as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["successful"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If a non-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," response or no response is returned, the delivery is considered ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["failed"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"retry-behavior","__idx":2},"children":["Retry Behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ChaChing automatically retries failed webhook deliveries."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Retries are triggered when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Network failure"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Timeout"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Non-",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," HTTP response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry Flow:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If delivery fails, webhook is retried"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["max retries NOT reached,"]}," retry continues"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["max retries reached,"]}," marked as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["failed"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retry Policy:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Attempts: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["5 times"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retry window: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["approximately 15 minutes"]}," (retries are spread across the retry window with increasing delays)"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["⚠️ Webhooks may be delivered multiple times. Ensure your system handles duplicates (use event ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},")."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"key-concepts","__idx":3},"children":["Key Concepts"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhooks-are-account-level","__idx":4},"children":["Webhooks are account-level"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhooks are configured ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per account"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each account has its own webhook endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Events generated in one account are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not shared"]}," with other accounts"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"multiple-webhook-endpoints","__idx":5},"children":["Multiple webhook endpoints"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can create ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["multiple webhook endpoints"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Events are sent to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["all active endpoints within the account"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-configuration","__idx":6},"children":["Webhook Configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhooks can be managed via the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["UI"]}," (Settings → Developer → Webhooks) or programmatically via the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REST API"]},". Both approaches support the full lifecycle: create, list, update, enable/disable, and delete endpoints."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Only users with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["SuperAdmin"]}," role can manage webhooks. For user roles details, refer to the section Manage → Users in the left panel of the ChaChing application."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"via-the-ui","__idx":7},"children":["Via the UI"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In ChaChing, go to Settings → Developer settings."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the Developer Settings, select the Webhooks tab to:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create webhook endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["View all endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable / disable endpoints"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Edit/Delete endpoints"]}]}]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/webhookconfiguration.8b195e9266a8b388bd8927aab440c9b256442f20098e5dcb540a2f619fdcdc8c.9c1bb791.jpg","alt":"webhookConfiguration.jpg","framed":false,"withLightbox":true,"width":"","height":""},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"creating-a-webhook","__idx":8},"children":["Creating a Webhook"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer Settings → Webhooks."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create webhook."]}]}]},{"$$mdtype":"Tag","name":"Image","attributes":{"src":"/assets/creatingwebhook.242679ccc044a98fe5a68c6ed7d93db5063a34f153d047562b1f36529c773557.9c1bb791.jpg","alt":"creatingWebhook.jpg","framed":false,"withLightbox":true,"width":"","height":""},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enter endpoint URL and then select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create endpoint"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After creation:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Webhook becomes ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["active"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Events start being delivered immediately"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"via-the-rest-api","__idx":9},"children":["Via the REST API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All endpoints require authentication."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoints","__idx":10},"children":["Endpoints"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Path"},"children":["Path"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhook/destination"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Create a new webhook endpoint"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhook/destination"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["List all webhook endpoints"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhook/destination/:id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update a webhook endpoint"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhook/destination/:id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete a webhook endpoint"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhook/destination/:id/enable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enable a webhook endpoint"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhook/destination/:id/disable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Disable a webhook endpoint"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/webhook/logs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retrieve webhook delivery logs"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-endpoint","__idx":11},"children":["Create Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"POST /webhook/destination\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request body:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"url\": \"https://your-server.com/webhook\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}," the created webhook destination object, including its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," and active status."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-endpoints","__idx":12},"children":["List Endpoints"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /webhook/destination\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}," array of all webhook destination objects for the account."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-endpoint","__idx":13},"children":["Update Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PUT /webhook/destination/:id\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Request body:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"url\": \"https://your-server.com/new-webhook\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"enable--disable-endpoint","__idx":14},"children":["Enable / Disable Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"PATCH /webhook/destination/:id/enable\nPATCH /webhook/destination/:id/disable\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No request body required."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete-endpoint","__idx":15},"children":["Delete Endpoint"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"DELETE /webhook/destination/:id\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"retrieve-delivery-logs","__idx":16},"children":["Retrieve Delivery Logs"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /webhook/logs\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}," list of webhook delivery log entries. Each entry includes the event type, payload, and status (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retry"]},")."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"event-types","__idx":17},"children":["Event Types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ChaChing generates webhook events for key system entities. Each event represents a specific change or action performed in the system."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note: When you create a webhook you receive ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ALL events without the ability to subscribe to a specific event type"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customer-events","__idx":18},"children":["Customer Events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.created"]}," — A new customer is created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.updated"]}," — An existing customer is updated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.deleted"]}," — A customer is deleted"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-method-events","__idx":19},"children":["Payment Method Events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_method.attached"]}," — A payment method is attached to a customer"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_method.detached"]}," — A payment method is detached from a customer"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"invoice-events","__idx":20},"children":["Invoice Events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.created"]}," — A new invoice is created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.deleted"]}," — An invoice is deleted"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.finalized"]}," — An invoice is finalized and ready for payment"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.sent"]}," — An invoice is sent to the customer"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.payment_succeeded"]}," — Invoice payment completed successfully"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.payment_failed"]}," — Invoice payment failed"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"subscription-events","__idx":21},"children":["Subscription Events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.created"]}," — A subscription is created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.updated"]}," — A subscription is updated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.canceled"]}," — A subscription is canceled"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.paused"]}," — A subscription is paused"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.resumed"]}," — A paused subscription is resumed"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"product-events","__idx":22},"children":["Product Events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.created"]}," — A product is created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.updated"]}," — A product is updated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.deleted"]}," — A product is deleted"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"price-events","__idx":23},"children":["Price Events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price.created"]}," — A price is created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price.updated"]}," — A price is updated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price.deleted"]}," — A price is deleted"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tax-events","__idx":24},"children":["Tax Events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tax.created"]}," — A tax configuration is created"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tax.updated"]}," — A tax configuration is updated"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"summary","__idx":25},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ChaChing currently supports ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["24 webhook event types"]}," across such entities as:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Payment Methods"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invoices"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subscriptions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Products"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prices"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Taxes"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"event-status","__idx":26},"children":["Event Status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook delivery has the following internal states:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}," → waiting to be sent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retry"]}," → retry in progress"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," → delivered successfully"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure"]}," → all retries exhausted"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"event-structure","__idx":27},"children":["Event Structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All ChaChing webhook events share a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["common envelope structure"]},", with the actual entity data contained inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," field."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-event-envelope","__idx":28},"children":["Common Event Envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every webhook sent by ChaChing follows this structure:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_123456\",\n \"event\": \"customer.updated\", // specific to the event type \n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n // Entity-specific payload\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fields-description","__idx":29},"children":["Fields Description"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," — Unique event identifier (used for deduplication)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," — Event type (see Event Types section)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]}," — Timestamp when the event was generated"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," — ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Entity payload"]}," (varies depending on event type)"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["❗ Important: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," already contains the object. There is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.object"]}," nesting"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customer-events-payload","__idx":30},"children":["Customer Events Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.updated"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customer.deleted"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema","__idx":31},"children":["Schema"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"cus_XXXXXXXX\",\n \"object\": \"customer\",\n \"name\": \"string\",\n \"email\": \"string\",\n \"description\": \"string | null\",\n \"phone\": \"string | null\",\n \"created\": 1672531200,\n \"currency\": \"string\",\n \"address\": [\n {\n \"city\": \"string\",\n \"country\": \"string\",\n \"line1\": \"string\",\n \"line2\": \"string\",\n \"postal_code\": \"string\",\n \"state\": \"string\"\n }\n ],\n \"shipping\": {\n \"name\": \"string\",\n \"phone\": \"string | null\",\n \"address\": {\n \"city\": \"string\",\n \"country\": \"string\",\n \"line1\": \"string\",\n \"line2\": \"string\",\n \"postal_code\": \"string\",\n \"state\": \"string\"\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example","__idx":32},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_111\",\n \"event\": \"customer.created\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"cus_NffrFeUfNV2Hib\",\n \"object\": \"customer\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"description\": \"My First Test Customer\",\n \"phone\": null,\n \"created\": 1680893993,\n \"currency\": \"USD\",\n \"address\": [\n {\n \"city\": \"San Francisco\",\n \"country\": \"US\",\n \"line1\": \"123 Market St\",\n \"line2\": \"Apt 4B\",\n \"postal_code\": \"94103\",\n \"state\": \"CA\"\n }\n ],\n \"shipping\": {\n \"name\": \"John Doe\",\n \"phone\": \"+1 (555) 123-4567\",\n \"address\": {\n \"city\": \"San Francisco\",\n \"country\": \"US\",\n \"line1\": \"123 Market St\",\n \"line2\": \"Apt 4B\",\n \"postal_code\": \"94103\",\n \"state\": \"CA\"\n }\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes","__idx":33},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["address"]}," field is an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["array of address objects"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipping.address"]}," is a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["single object"]}," (not an array)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["phone"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," fields may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Timestamps are in Unix format (seconds)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-method-events-payload","__idx":34},"children":["Payment Method Events Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_method.attached"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_method.detached"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema-1","__idx":35},"children":["Schema"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"pm_XXXXXXXX\",\n \"object\": \"payment_method\",\n \"allow_redisplay\": \"string\",\n \"billing_details\": {\n \"address\": {\n \"city\": \"string | null\",\n \"country\": \"string | null\",\n \"line1\": \"string | null\",\n \"line2\": \"string | null\",\n \"postal_code\": \"string | null\",\n \"state\": \"string | null\"\n },\n \"email\": \"string | null\",\n \"name\": \"string | null\",\n \"phone\": \"string | null\"\n },\n \"created\": 1672531200,\n \"customer\": \"cus_XXXXXXXX | null\",\n \"livemode\": false,\n \"metadata\": {},\n \"type\": \"string\",\n \"us_bank_account\": {\n \"account_holder_type\": \"individual | company\",\n \"account_type\": \"checking | savings\",\n \"bank_name\": \"string\",\n \"financial_connections_account\": \"string | null\",\n \"fingerprint\": \"string\",\n \"last4\": \"string\",\n \"networks\": {\n \"preferred\": \"string\",\n \"supported\": [\"string\"]\n },\n \"routing_number\": \"string\",\n \"status_details\": {}\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-1","__idx":36},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_123\",\n \"event\": \"payment_method.attached\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"pm_1Q0PsIJvEtkwdCNYMSaVuRz6\",\n \"object\": \"payment_method\",\n \"allow_redisplay\": \"unspecified\",\n \"billing_details\": {\n \"address\": {\n \"city\": null,\n \"country\": null,\n \"line1\": null,\n \"line2\": null,\n \"postal_code\": null,\n \"state\": null\n },\n \"email\": null,\n \"name\": \"John Doe\",\n \"phone\": null\n },\n \"created\": 1726673582,\n \"customer\": null,\n \"livemode\": false,\n \"metadata\": {},\n \"type\": \"us_bank_account\",\n \"us_bank_account\": {\n \"account_holder_type\": \"individual\",\n \"account_type\": \"checking\",\n \"bank_name\": \"STRIPE TEST BANK\",\n \"financial_connections_account\": null,\n \"fingerprint\": \"LstWJFsCK7P349Bg\",\n \"last4\": \"6789\",\n \"networks\": {\n \"preferred\": \"ach\",\n \"supported\": [\n \"ach\"\n ]\n },\n \"routing_number\": \"110000000\",\n \"status_details\": {}\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes-1","__idx":37},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," field defines the structure of the payment method (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["us_bank_account"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The corresponding object (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["us_bank_account"]},") is included based on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some fields may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," depending on the payment method and available data"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"invoice-events-payload","__idx":38},"children":["Invoice Events Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.deleted"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.finalized"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.sent"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.payment_succeeded"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invoice.payment_failed"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema-2","__idx":39},"children":["Schema"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"string\",\n \"object\": \"invoice\",\n \"account_country\": \"string\",\n \"account_name\": \"string\",\n \"amount_due\": 0,\n \"amount_paid\": 0,\n \"amount_remaining\": 0,\n \"attempt_count\": 0,\n \"attempted\": true,\n \"billing_reason\": \"string\",\n \"collection_method\": \"string\",\n \"created\": 1672531200,\n \"currency\": \"string\",\n \"customer\": \"cus_XXXXXXXX\",\n \"customer_address\": {\n \"city\": \"string\",\n \"country\": \"string\",\n \"line1\": \"string\",\n \"line2\": \"string\",\n \"postal_code\": \"string\",\n \"state\": \"string\"\n },\n \"customer_email\": \"string\",\n \"customer_name\": \"string\",\n \"customer_phone\": \"string\",\n \"lines\": [],\n \"number\": \"string\",\n \"paid\": true,\n \"period_end\": 1672531200,\n \"period_start\": 1672531200,\n \"status\": \"draft | open | paid | void\",\n \"status_transitions\": {\n \"finalized_at\": 1672531200,\n \"paid_at\": 1672531200,\n \"voided_at\": 1672531200\n },\n \"subscription\": \"sub_XXXXXXXX\",\n \"subtotal\": 0,\n \"subtotal_excluding_tax\": 0,\n \"tax\": 0,\n \"total\": 0,\n \"total_excluding_tax\": 0,\n \"total_taxes\": {\n \"amount\": 0,\n \"tax_behavior\": \"inclusive | exclusive\",\n \"tax_rate\": \"txr_XXXXXXXX\",\n \"taxable_amount\": 0\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-2","__idx":40},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_456\",\n \"event\": \"invoice.payment_succeeded\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"a80baa67-1341-4184-b712-b6f9b85b5a2b\",\n \"object\": \"invoice\",\n \"account_country\": \"US\",\n \"account_name\": \"Acme Corp\",\n \"amount_due\": 1500,\n \"amount_paid\": 500,\n \"amount_remaining\": 1000,\n \"attempt_count\": 1,\n \"attempted\": true,\n \"billing_reason\": \"subscription\",\n \"collection_method\": \"charge_automatically\",\n \"created\": 1680645568,\n \"currency\": \"USD\",\n \"customer\": \"cus_383fda0065594749023e8c8d\",\n \"customer_address\": {\n \"city\": \"San Francisco\",\n \"country\": \"US\",\n \"line1\": \"123 Market St\",\n \"line2\": \"Apt 4B\",\n \"postal_code\": \"94103\",\n \"state\": \"CA\"\n },\n \"customer_email\": \"john.doe@example.com\",\n \"customer_name\": \"John Doe\",\n \"customer_phone\": \"+1234567890\",\n \"lines\": [],\n \"number\": \"INV-1001\",\n \"paid\": true,\n \"period_end\": 1680645568,\n \"period_start\": 1680645568,\n \"status\": \"paid\",\n \"status_transitions\": {\n \"finalized_at\": 1680645568,\n \"paid_at\": 1680645568,\n \"voided_at\": 1680645568\n },\n \"subscription\": \"sub_Wm45f5PGQvv67azFeH1z7PO3\",\n \"subtotal\": 1500,\n \"subtotal_excluding_tax\": 1500,\n \"tax\": 150,\n \"total\": 1650,\n \"total_excluding_tax\": 1500,\n \"total_taxes\": {\n \"amount\": 150,\n \"tax_behavior\": \"exclusive\",\n \"tax_rate\": \"txr_1S2tlWDZYOQH9uHkltYEi1ap\",\n \"taxable_amount\": 1500\n }\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes-2","__idx":41},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field reflects the current lifecycle state of the invoice"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status_transitions"]}," shows timestamps for key lifecycle changes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Monetary values are represented in the smallest currency unit (e.g., cents)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lines"]}," field contains invoice line items (structure may vary)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Some fields may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," depending on invoice state and configuration"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"subscription-events-payload","__idx":42},"children":["Subscription Events Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.updated"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.canceled"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.paused"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscription.resumed"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema-3","__idx":43},"children":["Schema"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"sub_XXXXXXXX\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": 1672531200,\n \"cancel_at\": 1672531200,\n \"cancel_at_period_end\": false,\n \"canceled_at\": 1672531200,\n \"collection_method\": \"string\",\n \"created\": 1672531200,\n \"currency\": \"string\",\n \"customer\": \"cus_XXXXXXXX\",\n \"ended_at\": 1672531200,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n []\n ],\n \"total_count\": 0\n },\n \"latest_invoice\": \"string\",\n \"start_date\": 1672531200,\n \"status\": \"active | canceled | paused\",\n \"trial_end\": 1672531200,\n \"trial_start\": 1672531200\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-3","__idx":44},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_789\",\n \"event\": \"subscription.created\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"sub_2FdhgypnsJQn9mZlY5qGaElL\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": 1679609767,\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"collection_method\": \"charge_automatically\",\n \"created\": 1679609767,\n \"currency\": \"USD\",\n \"customer\": \"cus_739c07713fd4b68565a969cd\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n []\n ],\n \"total_count\": 1\n },\n \"latest_invoice\": \"58d0f1c9-ca00-4998-8e89-d74a290b4df6\",\n \"start_date\": 1679609767,\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_start\": null\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes-3","__idx":45},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field represents the current subscription state (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paused"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fields like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancel_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled_at"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ended_at"]}," may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," depending on lifecycle state"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["items.data"]}," contains subscription items (structure depends on pricing configuration)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["latest_invoice"]}," links the most recent invoice associated with the subscription"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Timestamps are in Unix format (seconds)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"product-events-payload","__idx":46},"children":["Product Events Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.updated"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product.deleted"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema-4","__idx":47},"children":["Schema"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"prod_XXXXXXXX\",\n \"object\": \"product\",\n \"active\": true,\n \"created\": 1672531200,\n \"default_price\": \"price_XXXXXXXX\",\n \"description\": \"string | null\",\n \"name\": \"string\",\n \"tax_code\": \"string\",\n \"updated\": 1672531200\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-4","__idx":48},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_321\",\n \"event\": \"product.updated\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"prod_xT4LfvxLMQb4s9uFNIbXf9pm\",\n \"object\": \"product\",\n \"active\": true,\n \"created\": 1760018761,\n \"default_price\": \"price_1SGKTmDZYOQH9uHk1vaSxPKa\",\n \"description\": null,\n \"name\": \"Gold Plan\",\n \"tax_code\": \"txcd_10000000\",\n \"updated\": 1753181495\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes-4","__idx":49},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["default_price"]}," field references the default price associated with the product"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," field may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," if not provided"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]}," field indicates whether the product is available for use"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Timestamps are in Unix format (seconds)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"price-events-payload","__idx":50},"children":["Price Events Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price.updated"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["price.deleted"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema-5","__idx":51},"children":["Schema"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"price_XXXXXXXX\",\n \"object\": \"price\",\n \"active\": true,\n \"created\": 1672531200,\n \"currency\": \"string\",\n \"description\": \"string | null\",\n \"product\": \"prod_XXXXXXXX | null\",\n \"recurring\": {\n \"interval\": \"day | week | month | year\",\n \"interval_count\": 0\n },\n \"tax_behavior\": \"inclusive | exclusive\",\n \"type\": \"one_time | recurring\",\n \"unit_amount\": 0,\n \"unit_amount_decimal\": \"string\",\n \"link\": \"string\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-5","__idx":52},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_654\",\n \"event\": \"price.created\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"price_1SGKTmDZYOQH9uHk1vaSxPKa\",\n \"object\": \"price\",\n \"active\": true,\n \"created\": 1760018761,\n \"currency\": \"USD\",\n \"description\": \"Premium Plan - Monthly\",\n \"product\": null,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"tax_behavior\": \"exclusive\",\n \"type\": \"one_time\",\n \"unit_amount\": 1000,\n \"unit_amount_decimal\": \"1000\",\n \"link\": \"string\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes-5","__idx":53},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," field defines whether the price is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one-time"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["recurring"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recurring"]}," object is relevant for subscription-based pricing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unit_amount"]}," is represented in the smallest currency unit (e.g., cents)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]}," may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," if not linked"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unit_amount_decimal"]}," provides a precise representation of the amount"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tax_behavior"]}," defines how taxes are applied (inclusive or exclusive)"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tax-events-payload","__idx":54},"children":["Tax Events Payload"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tax.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tax.updated"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"schema-6","__idx":55},"children":["Schema"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"txr_XXXXXXXX\",\n \"object\": \"tax_rate\",\n \"active\": true,\n \"country\": \"string\",\n \"created\": 1672531200,\n \"description\": \"string | null\",\n \"display_name\": \"string\",\n \"inclusive\": true,\n \"percentage\": 0,\n \"tax_type\": \"string\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-6","__idx":56},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_987\",\n \"event\": \"tax.created\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"txr_inQ4hbLZPyljDXFRCEnjtEqK\",\n \"object\": \"tax_rate\",\n \"active\": true,\n \"country\": \"US\",\n \"created\": 1678833149,\n \"description\": \"State sales tax\",\n \"display_name\": \"Sales Tax\",\n \"inclusive\": true,\n \"percentage\": 7.25,\n \"tax_type\": \"Custom\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"notes-6","__idx":57},"children":["Notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["percentage"]}," field represents the tax rate (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["7.25"]}," = 7.25%)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inclusive"]}," field indicates whether the tax is included in the price"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tax_type"]}," defines the type of tax configuration (e.g., custom)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," field may be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," depending on configuration"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"important-notes","__idx":58},"children":["Important Notes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The data object is contained inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," field."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," field contains the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["full entity object"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deleted events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["May contain limited data (e.g., only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Should not be assumed to contain full object"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always rely on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}," field to determine how to parse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"payload-behavior","__idx":59},"children":["Payload Behavior"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The payload reflects the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["entity after change"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Example:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Customer updated → full updated customer data is sent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Subscription created → full subscription object is sent"]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"example-event","__idx":60},"children":["Example Event"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"id\": \"evt_789\",\n \"event\": \"customer.updated\",\n \"createdAt\": \"2026-03-13T11:15:00Z\",\n \"data\": {\n \"id\": \"cus_123\",\n \"email\": \"user@example.com\",\n \"status\": \"active\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-delivery","__idx":61},"children":["Webhook Delivery"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Method: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Content-Type: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application/json"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sent to: configured endpoint URL in ChaChing application."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-signatures","__idx":62},"children":["Webhook Signatures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ChaChing signs every webhook delivery with an HMAC-SHA256 signature. Verify this signature to confirm the request originated from ChaChing and that the payload has not been tampered with."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signature-header","__idx":63},"children":["Signature Header"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each request includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Chaching-Signature"]}," header in the following format:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Chaching-Signature: t=,v1=\n"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t"]}," — Unix timestamp of when the request was sent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v1"]}," — HMAC-SHA256 hex digest of the signed payload"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signing-algorithm","__idx":64},"children":["Signing Algorithm"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The signature is computed as:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"HMAC-SHA256(secretKey, \"{timestamp}.{raw_json_body}\")\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]}," is your account's secret key, retrieved via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /account/keys"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}," is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t"]}," value from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Chaching-Signature"]}," header"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["raw_json_body"]}," is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw, unparsed"]}," request body"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["⚠️ Always compute the signature against the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw request body"]},", before any JSON parsing. Re-serializing a parsed object may alter whitespace or key ordering and cause signature verification to fail."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"obtaining-your-secret-key","__idx":65},"children":["Obtaining Your Secret Key"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /account/keys\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verification-examples","__idx":66},"children":["Verification Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"nodejs","__idx":67},"children":["Node.js"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const crypto = require('crypto');\n\nfunction verifyWebhookSignature(rawBody, signatureHeader, secretKey) {\n const parts = {};\n signatureHeader.split(',').forEach(part => {\n const idx = part.indexOf('=');\n parts[part.slice(0, idx)] = part.slice(idx + 1);\n });\n\n const timestamp = parts['t'];\n const expectedSig = parts['v1'];\n\n const payload = `${timestamp}.${rawBody}`;\n const computedSig = crypto\n .createHmac('sha256', secretKey)\n .update(payload)\n .digest('hex');\n\n return crypto.timingSafeEqual(\n Buffer.from(computedSig),\n Buffer.from(expectedSig)\n );\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python","__idx":68},"children":["Python"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import hmac\nimport hashlib\n\ndef verify_webhook_signature(raw_body: str, signature_header: str, secret_key: str) -> bool:\n parts = dict(part.split('=', 1) for part in signature_header.split(','))\n timestamp = parts['t']\n expected_sig = parts['v1']\n\n payload = f\"{timestamp}.{raw_body}\"\n computed_sig = hmac.new(\n secret_key.encode('utf-8'),\n payload.encode('utf-8'),\n hashlib.sha256\n ).hexdigest()\n\n return hmac.compare_digest(computed_sig, expected_sig)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ℹ️ Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["crypto.timingSafeEqual"]}," (Node.js) or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hmac.compare_digest"]}," (Python) to prevent timing-based attacks when comparing signatures."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-logs","__idx":69},"children":["Webhook Logs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ChaChing stores webhook delivery history."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Logs include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Event type"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Payload"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Status (success / failed / retry)"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Logs reflect actual data sent from the database"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"handling-webhooks-client-side","__idx":70},"children":["Handling Webhooks (Client Side)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When receiving a webhook:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Accept HTTP POST request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parse JSON payload"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Process ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Return HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"important-notes-for-integrators","__idx":71},"children":["Important Notes for Integrators"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["No event filtering"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You will receive ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["all events"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["➡ You must filter by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," in your system"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payload varies per event"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," structure depends on event type"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["➡ You must handle multiple schemas"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Retries may cause duplicates"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["➡ Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," to deduplicate events"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Endpoint must be stable"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["➡ If your endpoint fails → events may be lost after retries"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"How Webhooks Work","id":"how-webhooks-work","depth":1},{"value":"Retry Behavior","id":"retry-behavior","depth":1},{"value":"Key Concepts","id":"key-concepts","depth":1},{"value":"Webhooks are account-level","id":"webhooks-are-account-level","depth":2},{"value":"Multiple webhook endpoints","id":"multiple-webhook-endpoints","depth":2},{"value":"Webhook Configuration","id":"webhook-configuration","depth":1},{"value":"Via the UI","id":"via-the-ui","depth":2},{"value":"Creating a Webhook","id":"creating-a-webhook","depth":3},{"value":"Via the REST API","id":"via-the-rest-api","depth":2},{"value":"Endpoints","id":"endpoints","depth":3},{"value":"Create Endpoint","id":"create-endpoint","depth":3},{"value":"List Endpoints","id":"list-endpoints","depth":3},{"value":"Update Endpoint","id":"update-endpoint","depth":3},{"value":"Enable / Disable Endpoint","id":"enable--disable-endpoint","depth":3},{"value":"Delete Endpoint","id":"delete-endpoint","depth":3},{"value":"Retrieve Delivery Logs","id":"retrieve-delivery-logs","depth":3},{"value":"Event Types","id":"event-types","depth":1},{"value":"Customer Events","id":"customer-events","depth":2},{"value":"Payment Method Events","id":"payment-method-events","depth":2},{"value":"Invoice Events","id":"invoice-events","depth":2},{"value":"Subscription Events","id":"subscription-events","depth":2},{"value":"Product Events","id":"product-events","depth":2},{"value":"Price Events","id":"price-events","depth":2},{"value":"Tax Events","id":"tax-events","depth":2},{"value":"Summary","id":"summary","depth":2},{"value":"Event Status","id":"event-status","depth":1},{"value":"Event Structure","id":"event-structure","depth":1},{"value":"Common Event Envelope","id":"common-event-envelope","depth":2},{"value":"Fields Description","id":"fields-description","depth":2},{"value":"Customer Events Payload","id":"customer-events-payload","depth":2},{"value":"Schema","id":"schema","depth":3},{"value":"Example","id":"example","depth":3},{"value":"Notes","id":"notes","depth":3},{"value":"Payment Method Events Payload","id":"payment-method-events-payload","depth":2},{"value":"Schema","id":"schema-1","depth":3},{"value":"Example","id":"example-1","depth":3},{"value":"Notes","id":"notes-1","depth":3},{"value":"Invoice Events Payload","id":"invoice-events-payload","depth":2},{"value":"Schema","id":"schema-2","depth":3},{"value":"Example","id":"example-2","depth":3},{"value":"Notes","id":"notes-2","depth":3},{"value":"Subscription Events Payload","id":"subscription-events-payload","depth":2},{"value":"Schema","id":"schema-3","depth":3},{"value":"Example","id":"example-3","depth":3},{"value":"Notes","id":"notes-3","depth":3},{"value":"Product Events Payload","id":"product-events-payload","depth":2},{"value":"Schema","id":"schema-4","depth":3},{"value":"Example","id":"example-4","depth":3},{"value":"Notes","id":"notes-4","depth":3},{"value":"Price Events Payload","id":"price-events-payload","depth":2},{"value":"Schema","id":"schema-5","depth":3},{"value":"Example","id":"example-5","depth":3},{"value":"Notes","id":"notes-5","depth":3},{"value":"Tax Events Payload","id":"tax-events-payload","depth":2},{"value":"Schema","id":"schema-6","depth":3},{"value":"Example","id":"example-6","depth":3},{"value":"Notes","id":"notes-6","depth":3},{"value":"Important Notes","id":"important-notes","depth":1},{"value":"Payload Behavior","id":"payload-behavior","depth":1},{"value":"Example Event","id":"example-event","depth":1},{"value":"Webhook Delivery","id":"webhook-delivery","depth":1},{"value":"Webhook Signatures","id":"webhook-signatures","depth":1},{"value":"Signature Header","id":"signature-header","depth":2},{"value":"Signing Algorithm","id":"signing-algorithm","depth":2},{"value":"Obtaining Your Secret Key","id":"obtaining-your-secret-key","depth":2},{"value":"Verification Examples","id":"verification-examples","depth":2},{"value":"Node.js","id":"nodejs","depth":3},{"value":"Python","id":"python","depth":3},{"value":"Webhook Logs","id":"webhook-logs","depth":1},{"value":"Handling Webhooks (Client Side)","id":"handling-webhooks-client-side","depth":1},{"value":"Important Notes for Integrators","id":"important-notes-for-integrators","depth":1}],"frontmatter":{"seo":{"title":"Webhooks"}},"lastModified":"2026-04-26T14:36:28.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-guide/webhook","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}