How do I set up a webhook for specific entities in Chargebee?

Problem Statement

You want a webhook endpoint to act only on events that belong to one entity in your business, such as a brand, business unit, or product line. Webhooks in Chargebee are configured for the whole site, so a webhook cannot be limited to the records of one entity.

Related Scenarios

• Setting up webhooks to filter events for specific business units
• Using custom fields to tag events for targeted tracking

Solution

For a given webhook endpoint, Chargebee sends all the events configured for that webhook, for every record on your site. The Events to Send setting limits which event types the webhook receives, but it cannot limit which records trigger those events. Any filtering by entity must happen on the webhook endpoint.

To make that filtering possible, mark the relevant records with a custom field. Custom field values are part of the resources included in the event payload, such as the customer, subscription, or invoice, so the system behind the webhook endpoint can filter events based on those values.

1. Create a custom field to mark the entity on the resources that appear in the events you need, such as customers, subscriptions, or invoices. Follow the steps in Creating Custom Fields. Then set the custom field's value on every record that belongs to the entity. Each of those records now carries the entity's value.
2. Configure a webhook that points to your webhook endpoint, and select the event types you need under Events to Send. Follow the steps in Configure Webhooks. Chargebee starts sending the selected events to your webhook endpoint.
3. On the webhook endpoint, inspect each received event and filter it based on the value of the custom field in the payload. Each custom field appears on its resource inside the event's content object under the custom field's API name, which starts with cf_. For example, a subscription custom field with the API name cf_brand appears as content.subscription.cf_brand. Process the events whose value matches the entity, and ignore the rest.

Your webhook endpoint now acts only on events for records that carry the entity's custom field value.

Important Notes

• Chargebee cannot restrict a webhook to specific entities. Filtering must be done on the webhook endpoint.
• Return a 2XX response for the events your webhook endpoint ignores, as well as for the events it processes. Chargebee retries any webhook call that does not receive a 2XX response.
• Webhooks are configured at the site level even when Multi Business Entity is enabled, so a webhook cannot be limited to one business entity either.
• A site can have up to five webhooks.