Webhook Endpoints
Register HTTPS endpoints to receive signed event notifications. Each delivery is signed following the Standard Webhooks specification — verify the webhook-id, webhook-timestamp, and webhook-signature headers against the endpoint secret (returned once on create / roll-secret) using one of the spec’s drop-in verification libraries instead of implementing the HMAC-SHA256 check yourself.
List webhook endpoints
Returns the company’s webhook endpoints, newest first.
query Parameters
pagePage number (1-based).
limitPage size (max 100).
List webhook endpoints › Responses
Paginated list of webhook endpoints.
totalTotal number of endpoints matching the query.
pageCurrent page (1-based).
pageSizePage size.
Create a webhook endpoint
Registers a new endpoint. url must be a public HTTPS URL. The response includes the signing secret exactly once — store it securely.
Create a webhook endpoint › Request Body
urlThe HTTPS URL events are delivered to. Must be a public https URL (loopback/private/link-local hosts are rejected).
enabledEventsThe events to subscribe to. Must contain at least one known event type.
Available events:
subscription.assigned— Fired when a subscription is assigned to a customer (may be future-dated / upcoming).subscription.started— Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.subscription.updated— Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).subscription.transitioned— Fired on a structural change: plan replace, product edit, billing cadence change, or realign.subscription.paused— Fired when a subscription is paused.subscription.resumed— Fired when a subscription resumes from a pause.subscription.trial_ended— Fired when a subscription trial ends and normal billing begins (the sub stays active).subscription.cancellation_scheduled— Fired when a future cancellation is scheduled for a subscription (still active until then).subscription.cancellation_cleared— Fired when a previously scheduled cancellation is cleared.subscription.churned— Fired when a subscription is cancelled/finalized — revoke entitlement on this event.subscription.billed— Fired once per (child) subscription when a billing run produces its invoice.subscription.payment_succeeded— Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal.subscription.error— Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).billing.invoice_sent— Fired when an invoice document is sent to the customer.billing.credit_note_sent— Fired when a credit note document is sent to the customer.customer.created— Fired when a customer is created (payload flags whether it was a portal self-signup).card.added— Fired when a card is successfully saved for a customer (provider-opaque).card.removed— Fired when a saved card is removed in-app or cancelled at the provider.card.updated— Fired when a saved card’s details change (network auto-update or refresh).card.expiring— Fired when a saved card is approaching expiry.card.expired— Fired when a saved card is observed to have expired.card.default_changed— Fired when the customer’s default card changes (explicit or auto-default).card.backup_changed— Fired when the customer’s designated backup card is set, replaced, or cleared.card.add_failed— Fired when a card-save attempt fails (decline or authentication failure).quote.sent— Fired when a quote is sent to the customer.quote.converted— Fired when a quote is converted into an order confirmation or an invoice.order_confirmation.sent— Fired when an order confirmation is sent to the customer.order_confirmation.converted— Fired when an order confirmation is converted into an invoice.project.created— Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).project.updated— Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.project.archived— Fired when a project is archived (its dimension is deactivated; postings history is preserved).
descriptionOptional human-facing description.
Create a webhook endpoint › Responses
Endpoint created. Includes the one-time signing secret.
idUnique identifier of the webhook endpoint.
urlThe HTTPS URL events are delivered to.
enabledEventsThe events this endpoint is subscribed to. An event is delivered to every enabled endpoint subscribed to its type.
Available events:
subscription.assigned— Fired when a subscription is assigned to a customer (may be future-dated / upcoming).subscription.started— Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.subscription.updated— Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).subscription.transitioned— Fired on a structural change: plan replace, product edit, billing cadence change, or realign.subscription.paused— Fired when a subscription is paused.subscription.resumed— Fired when a subscription resumes from a pause.subscription.trial_ended— Fired when a subscription trial ends and normal billing begins (the sub stays active).subscription.cancellation_scheduled— Fired when a future cancellation is scheduled for a subscription (still active until then).subscription.cancellation_cleared— Fired when a previously scheduled cancellation is cleared.subscription.churned— Fired when a subscription is cancelled/finalized — revoke entitlement on this event.subscription.billed— Fired once per (child) subscription when a billing run produces its invoice.subscription.payment_succeeded— Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal.subscription.error— Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).billing.invoice_sent— Fired when an invoice document is sent to the customer.billing.credit_note_sent— Fired when a credit note document is sent to the customer.customer.created— Fired when a customer is created (payload flags whether it was a portal self-signup).card.added— Fired when a card is successfully saved for a customer (provider-opaque).card.removed— Fired when a saved card is removed in-app or cancelled at the provider.card.updated— Fired when a saved card’s details change (network auto-update or refresh).card.expiring— Fired when a saved card is approaching expiry.card.expired— Fired when a saved card is observed to have expired.card.default_changed— Fired when the customer’s default card changes (explicit or auto-default).card.backup_changed— Fired when the customer’s designated backup card is set, replaced, or cleared.card.add_failed— Fired when a card-save attempt fails (decline or authentication failure).quote.sent— Fired when a quote is sent to the customer.quote.converted— Fired when a quote is converted into an order confirmation or an invoice.order_confirmation.sent— Fired when an order confirmation is sent to the customer.order_confirmation.converted— Fired when an order confirmation is converted into an invoice.project.created— Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).project.updated— Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.project.archived— Fired when a project is archived (its dimension is deactivated; postings history is preserved).
statusDelivery status. disabled endpoints are retained but receive no events.
createdAtISO 8601 creation timestamp.
updatedAtISO 8601 last-update timestamp.
secretThe signing secret (shown only on create and roll-secret). Used to verify the webhook-signature header.
descriptionOptional human-facing description of what this endpoint is used for.
Retrieve a webhook endpoint
Retrieves a single webhook endpoint configuration by its id. Returns 404
with code WEBHOOK_ENDPOINT_NOT_FOUND when the endpoint does not exist in
your company.
Required Scope
webhook-endpoints-read
path Parameters
idThe webhook endpoint id.
Retrieve a webhook endpoint › Responses
The webhook endpoint.
idUnique identifier of the webhook endpoint.
urlThe HTTPS URL events are delivered to.
enabledEventsThe events this endpoint is subscribed to. An event is delivered to every enabled endpoint subscribed to its type.
Available events:
subscription.assigned— Fired when a subscription is assigned to a customer (may be future-dated / upcoming).subscription.started— Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.subscription.updated— Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).subscription.transitioned— Fired on a structural change: plan replace, product edit, billing cadence change, or realign.subscription.paused— Fired when a subscription is paused.subscription.resumed— Fired when a subscription resumes from a pause.subscription.trial_ended— Fired when a subscription trial ends and normal billing begins (the sub stays active).subscription.cancellation_scheduled— Fired when a future cancellation is scheduled for a subscription (still active until then).subscription.cancellation_cleared— Fired when a previously scheduled cancellation is cleared.subscription.churned— Fired when a subscription is cancelled/finalized — revoke entitlement on this event.subscription.billed— Fired once per (child) subscription when a billing run produces its invoice.subscription.payment_succeeded— Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal.subscription.error— Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).billing.invoice_sent— Fired when an invoice document is sent to the customer.billing.credit_note_sent— Fired when a credit note document is sent to the customer.customer.created— Fired when a customer is created (payload flags whether it was a portal self-signup).card.added— Fired when a card is successfully saved for a customer (provider-opaque).card.removed— Fired when a saved card is removed in-app or cancelled at the provider.card.updated— Fired when a saved card’s details change (network auto-update or refresh).card.expiring— Fired when a saved card is approaching expiry.card.expired— Fired when a saved card is observed to have expired.card.default_changed— Fired when the customer’s default card changes (explicit or auto-default).card.backup_changed— Fired when the customer’s designated backup card is set, replaced, or cleared.card.add_failed— Fired when a card-save attempt fails (decline or authentication failure).quote.sent— Fired when a quote is sent to the customer.quote.converted— Fired when a quote is converted into an order confirmation or an invoice.order_confirmation.sent— Fired when an order confirmation is sent to the customer.order_confirmation.converted— Fired when an order confirmation is converted into an invoice.project.created— Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).project.updated— Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.project.archived— Fired when a project is archived (its dimension is deactivated; postings history is preserved).
statusDelivery status. disabled endpoints are retained but receive no events.
createdAtISO 8601 creation timestamp.
updatedAtISO 8601 last-update timestamp.
descriptionOptional human-facing description of what this endpoint is used for.
Update a webhook endpoint
All fields optional. enabledEvents replaces the full subscription set. Send description: null to clear it.
path Parameters
idThe webhook endpoint id.
Update a webhook endpoint › Request Body
urlNew HTTPS delivery URL.
enabledEventsReplace the full set of subscribed events.
Available events:
subscription.assigned— Fired when a subscription is assigned to a customer (may be future-dated / upcoming).subscription.started— Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.subscription.updated— Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).subscription.transitioned— Fired on a structural change: plan replace, product edit, billing cadence change, or realign.subscription.paused— Fired when a subscription is paused.subscription.resumed— Fired when a subscription resumes from a pause.subscription.trial_ended— Fired when a subscription trial ends and normal billing begins (the sub stays active).subscription.cancellation_scheduled— Fired when a future cancellation is scheduled for a subscription (still active until then).subscription.cancellation_cleared— Fired when a previously scheduled cancellation is cleared.subscription.churned— Fired when a subscription is cancelled/finalized — revoke entitlement on this event.subscription.billed— Fired once per (child) subscription when a billing run produces its invoice.subscription.payment_succeeded— Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal.subscription.error— Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).billing.invoice_sent— Fired when an invoice document is sent to the customer.billing.credit_note_sent— Fired when a credit note document is sent to the customer.customer.created— Fired when a customer is created (payload flags whether it was a portal self-signup).card.added— Fired when a card is successfully saved for a customer (provider-opaque).card.removed— Fired when a saved card is removed in-app or cancelled at the provider.card.updated— Fired when a saved card’s details change (network auto-update or refresh).card.expiring— Fired when a saved card is approaching expiry.card.expired— Fired when a saved card is observed to have expired.card.default_changed— Fired when the customer’s default card changes (explicit or auto-default).card.backup_changed— Fired when the customer’s designated backup card is set, replaced, or cleared.card.add_failed— Fired when a card-save attempt fails (decline or authentication failure).quote.sent— Fired when a quote is sent to the customer.quote.converted— Fired when a quote is converted into an order confirmation or an invoice.order_confirmation.sent— Fired when an order confirmation is sent to the customer.order_confirmation.converted— Fired when an order confirmation is converted into an invoice.project.created— Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).project.updated— Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.project.archived— Fired when a project is archived (its dimension is deactivated; postings history is preserved).
statusEnable or disable delivery without deleting the endpoint.
descriptionUpdate the description. Send null to clear it.
Update a webhook endpoint › Responses
The updated webhook endpoint.
idUnique identifier of the webhook endpoint.
urlThe HTTPS URL events are delivered to.
enabledEventsThe events this endpoint is subscribed to. An event is delivered to every enabled endpoint subscribed to its type.
Available events:
subscription.assigned— Fired when a subscription is assigned to a customer (may be future-dated / upcoming).subscription.started— Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.subscription.updated— Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).subscription.transitioned— Fired on a structural change: plan replace, product edit, billing cadence change, or realign.subscription.paused— Fired when a subscription is paused.subscription.resumed— Fired when a subscription resumes from a pause.subscription.trial_ended— Fired when a subscription trial ends and normal billing begins (the sub stays active).subscription.cancellation_scheduled— Fired when a future cancellation is scheduled for a subscription (still active until then).subscription.cancellation_cleared— Fired when a previously scheduled cancellation is cleared.subscription.churned— Fired when a subscription is cancelled/finalized — revoke entitlement on this event.subscription.billed— Fired once per (child) subscription when a billing run produces its invoice.subscription.payment_succeeded— Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal.subscription.error— Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).billing.invoice_sent— Fired when an invoice document is sent to the customer.billing.credit_note_sent— Fired when a credit note document is sent to the customer.customer.created— Fired when a customer is created (payload flags whether it was a portal self-signup).card.added— Fired when a card is successfully saved for a customer (provider-opaque).card.removed— Fired when a saved card is removed in-app or cancelled at the provider.card.updated— Fired when a saved card’s details change (network auto-update or refresh).card.expiring— Fired when a saved card is approaching expiry.card.expired— Fired when a saved card is observed to have expired.card.default_changed— Fired when the customer’s default card changes (explicit or auto-default).card.backup_changed— Fired when the customer’s designated backup card is set, replaced, or cleared.card.add_failed— Fired when a card-save attempt fails (decline or authentication failure).quote.sent— Fired when a quote is sent to the customer.quote.converted— Fired when a quote is converted into an order confirmation or an invoice.order_confirmation.sent— Fired when an order confirmation is sent to the customer.order_confirmation.converted— Fired when an order confirmation is converted into an invoice.project.created— Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).project.updated— Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.project.archived— Fired when a project is archived (its dimension is deactivated; postings history is preserved).
statusDelivery status. disabled endpoints are retained but receive no events.
createdAtISO 8601 creation timestamp.
updatedAtISO 8601 last-update timestamp.
descriptionOptional human-facing description of what this endpoint is used for.
Roll the signing secret
Generates a new signing secret for the endpoint, returned once. The endpoint id is unchanged. The previous secret stops verifying immediately.
path Parameters
idThe webhook endpoint id.
Roll the signing secret › Responses
The endpoint with its new one-time signing secret.
idUnique identifier of the webhook endpoint.
urlThe HTTPS URL events are delivered to.
enabledEventsThe events this endpoint is subscribed to. An event is delivered to every enabled endpoint subscribed to its type.
Available events:
subscription.assigned— Fired when a subscription is assigned to a customer (may be future-dated / upcoming).subscription.started— Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.subscription.updated— Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).subscription.transitioned— Fired on a structural change: plan replace, product edit, billing cadence change, or realign.subscription.paused— Fired when a subscription is paused.subscription.resumed— Fired when a subscription resumes from a pause.subscription.trial_ended— Fired when a subscription trial ends and normal billing begins (the sub stays active).subscription.cancellation_scheduled— Fired when a future cancellation is scheduled for a subscription (still active until then).subscription.cancellation_cleared— Fired when a previously scheduled cancellation is cleared.subscription.churned— Fired when a subscription is cancelled/finalized — revoke entitlement on this event.subscription.billed— Fired once per (child) subscription when a billing run produces its invoice.subscription.payment_succeeded— Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal.subscription.error— Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).billing.invoice_sent— Fired when an invoice document is sent to the customer.billing.credit_note_sent— Fired when a credit note document is sent to the customer.customer.created— Fired when a customer is created (payload flags whether it was a portal self-signup).card.added— Fired when a card is successfully saved for a customer (provider-opaque).card.removed— Fired when a saved card is removed in-app or cancelled at the provider.card.updated— Fired when a saved card’s details change (network auto-update or refresh).card.expiring— Fired when a saved card is approaching expiry.card.expired— Fired when a saved card is observed to have expired.card.default_changed— Fired when the customer’s default card changes (explicit or auto-default).card.backup_changed— Fired when the customer’s designated backup card is set, replaced, or cleared.card.add_failed— Fired when a card-save attempt fails (decline or authentication failure).quote.sent— Fired when a quote is sent to the customer.quote.converted— Fired when a quote is converted into an order confirmation or an invoice.order_confirmation.sent— Fired when an order confirmation is sent to the customer.order_confirmation.converted— Fired when an order confirmation is converted into an invoice.project.created— Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).project.updated— Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.project.archived— Fired when a project is archived (its dimension is deactivated; postings history is preserved).
statusDelivery status. disabled endpoints are retained but receive no events.
createdAtISO 8601 creation timestamp.
updatedAtISO 8601 last-update timestamp.
secretThe signing secret (shown only on create and roll-secret). Used to verify the webhook-signature header.
descriptionOptional human-facing description of what this endpoint is used for.
Send a test event
Synchronously POSTs a signed sample payload for the given event to the endpoint’s URL and returns the result. No delivery is recorded.
path Parameters
idThe webhook endpoint id.
Send a test event › Request Body
eventThe event type to simulate. Must be one of the endpoint’s subscribed events.
Available events:
subscription.assigned— Fired when a subscription is assigned to a customer (may be future-dated / upcoming).subscription.started— Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned.subscription.updated— Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction).subscription.transitioned— Fired on a structural change: plan replace, product edit, billing cadence change, or realign.subscription.paused— Fired when a subscription is paused.subscription.resumed— Fired when a subscription resumes from a pause.subscription.trial_ended— Fired when a subscription trial ends and normal billing begins (the sub stays active).subscription.cancellation_scheduled— Fired when a future cancellation is scheduled for a subscription (still active until then).subscription.cancellation_cleared— Fired when a previously scheduled cancellation is cleared.subscription.churned— Fired when a subscription is cancelled/finalized — revoke entitlement on this event.subscription.billed— Fired once per (child) subscription when a billing run produces its invoice.subscription.payment_succeeded— Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal.subscription.error— Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient).billing.invoice_sent— Fired when an invoice document is sent to the customer.billing.credit_note_sent— Fired when a credit note document is sent to the customer.customer.created— Fired when a customer is created (payload flags whether it was a portal self-signup).card.added— Fired when a card is successfully saved for a customer (provider-opaque).card.removed— Fired when a saved card is removed in-app or cancelled at the provider.card.updated— Fired when a saved card’s details change (network auto-update or refresh).card.expiring— Fired when a saved card is approaching expiry.card.expired— Fired when a saved card is observed to have expired.card.default_changed— Fired when the customer’s default card changes (explicit or auto-default).card.backup_changed— Fired when the customer’s designated backup card is set, replaced, or cleared.card.add_failed— Fired when a card-save attempt fails (decline or authentication failure).quote.sent— Fired when a quote is sent to the customer.quote.converted— Fired when a quote is converted into an order confirmation or an invoice.order_confirmation.sent— Fired when an order confirmation is sent to the customer.order_confirmation.converted— Fired when an order confirmation is converted into an invoice.project.created— Fired when a project is created (payload carries the owned dimension id for correlation with the dimensions API).project.updated— Fired when a project's fields are updated (payload lists the changed field names). Also fires on un-archive.project.archived— Fired when a project is archived (its dimension is deactivated; postings history is preserved).
Send a test event › Responses
The probe result.
successWhether the endpoint responded with a 2xx status.
durationMsRound-trip time of the probe in milliseconds.
statusCodeHTTP status returned by the endpoint, or null on a transport error.
errorTransport/error message when the probe failed, otherwise null.