Skip to main content
Invoicing webhooks provide your app with real-time invoice status updates. By subscribing your webhook endpoint you will receive a notification every time an invoice status changes.

Setup

Prerequisites

You will need:
  • Your CDP API Key ID and secret
  • A webhook notification HTTPS URL
  • Install the CDP CLI and run cdp env live --key-file ./cdp_api_key.json once to configure credentials.

Create a webhook subscription

  1. Review the configuration you’ll submit:
Important configuration notes:
  • labels is a required field, but can be an empty object {}
  • target.url should be your webhook endpoint that will receive the events
  • You can also set a headers object in target if your url requires specific headers. Pass it inline with 'target.headers:={"custom-header":"value"}'.
  • All Invoicing event types should be included to ensure you receive notifications for every invoice state change:
  1. Create the webhook subscription with the CDP CLI:
Response:

Manage subscriptions

Use the subscriptionId from the response to view, update, or delete the subscription. List all subscriptions
View specified subscription details by subscription ID
Update subscription update is a full replace — pass every field, including ones you aren’t changing:
Delete subscription
List subscription events View delivery attempts for a subscription, including delivery status, retry count, and HTTP response details:
You can narrow results with the following optional query parameters: Results are limited to the 50 most recent events, returned newest first. Example with filters:

Webhook signature verification

X-Hook0-Signature is deprecated and will eventually be removed. Use X-Webhook-Signature going forward. Both headers are sent with identical values and use the same verification algorithm and webhook secret.
Verify webhook signatures to ensure that requests are authentic. This protects your application from forged webhooks and potential security threats.

How it works

When you create a webhook subscription, the response includes a secret. Use this value to verify that incoming webhooks are authentic. Each webhook request includes an X-Webhook-Signature header containing:
  • t field - the timestamp
  • h field - list of headers included in the signature
  • v1 field - the signature

Implementation

Here’s an example of how to verify webhook signatures:
Node.js
And in your application:
Node.js

Next steps

Once your subscription is created, your endpoint will begin receiving webhook events for invoices!

Sample invoice event payload