Webhooks
Webhook docs read differently from endpoints: you are documenting an event your
service sends to the customer’s server. The Webhook component lays out the
event, its payload, and an example, with the same sticky rail as the API kit.
An event
invoice.paidDelivered to your webhook endpoint as a POST request when this event occurs.
Sent when an invoice is paid in full.
Payload
id string Unique id for the event.
type string The event type, always invoice.paid here.
data object The invoice that was paid.
{ "id": "evt_1abc", "type": "invoice.paid", "data": { "id": "in_9xy", "amount": 4200, "currency": "usd" }}Usage
Wrap the event in <Webhook> and document the payload with ResponseField, then
add a ResponseExample (or ObjectExample) with a fenced code block for the
sample event:
<Webhook event="invoice.paid" method="POST" description="Sent when an invoice is paid."> ## Payload <ResponseField name="id" type="string">Unique id for the event.</ResponseField> <ResponseExample title="Example event"> (a fenced json block with the sample payload) </ResponseExample></Webhook>It works just like the API components, so any of
ResponseField, ResponseExample, and ObjectExample are available inside.
Listing events
EventList renders an index of every event you send. Link each one to its
detail page.
invoice.paid An invoice was paid in full. invoice.payment_failed A payment attempt failed. customer.created A new customer was created. <EventList> <Event name="invoice.paid" href="/webhooks/invoice-paid">An invoice was paid.</Event> <Event name="customer.created" href="/webhooks/customer-created">A customer was created.</Event></EventList>Props
Webhook
| Prop | Type | Description |
|---|---|---|
event |
string |
The event type, e.g. invoice.paid |
method |
string |
Delivery method (default POST) |
description |
string |
Short summary of when the event fires |
Event
| Prop | Type | Description |
|---|---|---|
name |
string |
The event type (required) |
href |
string |
Link to the event’s detail page |