Webhooks Reference

Webhooks are sent as HTTP POST requests to your URL with a form-encoded body (content-type: application/x-www-form-urlencoded) for easy parsing in almost any programming language.

All webhooks contain the following keys:

Webhook Limitations

Advanced Billing places two limitations on your site for how webhooks can be used. These limitations include data retention (the amount of time old webhooks are stored) and the number of endpoints allowed per site. For more information, refer to how webhooks are limited.

Webhook Timestamps

Webhooks sent from Advanced Billing use EST for all content in the payload body. In contrast, API responses from Advanced Billing use the timezone of the current site.

Webhook Acknowledgment and Automatic Retries

Upon receiving a webhook, you should accept it by returning an HTTP "200 OK" response as quickly as possible. Sending any other response (e.g., "500 Internal Server Error," "404 Not Found") or failing to respond within approximately 15 seconds will trigger automatic retries.

Advanced Billing will attempt to send each webhook event up to five times before giving up. The retries follow a backoff schedule:

If you use the webhook replay feature via the webhook API or the webhook panel, avoid duplicate actions by following these suggestions:

• Use the unique webhook ID to track which webhooks you’ve already processed.
• Do not replay webhooks until the last_attempt_at timestamp is well outside the automatic retry intervals.

Inoperative Endpoints

Merchants often set up temporary webhook endpoints for testing purposes but forget to deactivate them. Inoperative endpoints can cause significant system strain as Advanced Billing attempts to deliver webhooks.

If repeated failures occur, Advanced Billing may pause or disable the endpoint. Below are examples of failure counts and their associated states:

Events

The following events are monitored within Advanced Billing and can generate Webhooks:

¹ The subscription object also contains information on the Customer and Product.
² This is usually caused by a failure at the payment gateway. This event is not generated for input validation errors (i.e. forgetting to fill in a field).
³ At the end of every recurring interval, either a renewal_success or a renewal_failure event is triggered once. If a card is declined and a renewal_failure is triggered, a subsequent payment that brings the account current will not generate a renewal_success (although it will generate a payment_success and a subscription_state_change)
⁴ payment_success or payment_failure are triggered for every payment attempted, whether it is for a normal renewal, a One-time Charge, a retry after failure, or a payment applied to an Invoice. Note that in some cases the payment may fail later, most commonly with ACH/eCheck and Direct Debit.
⁵ Note that the subscription object you are given contains keys for both previous_state and state so you can track the changes.
⁶ The expiring_card webhook is sent on the 1st, 15th and 7 days before the end of the month. This will identify all cards expiring in the current month.
⁷Additions of new PayPal accounts, changes/deletions of bank account / ACH type payment profiles do not currently generate any webhooks.
⁸ Component allocations are not currently included in the signup_success webhook.

Statement Events

At the end of every period (e.g., at renewal), a statement_closed or statement_settled webhook is triggered. The statement_settled webhook indicates that the statement closed and payment was successfully received (or payment was not required). The statement_closed webhook indicates that the statement closed but payment was not successfully received.

For example, if you receive a statement_closed webhook for statement #3, you will also receive a statement_settled webhook for statement #3 at a later time if the statement becomes paid (e.g., after a dunning retry or card update).

Payloads

The resource objects sent as payloads typically contain the same information as the corresponding API resource. Site payload objects include the site’s id and subdomain. For payload examples for each type of event, refer to the Payload Examples article.

Webhook Verification

Using your Site shared key and a “signature” (signature_hmac_sha_256) that is calculated and sent with the webhook, you can verify the authenticity and integrity of a webhook.

Deprecation

Previously, the signature was calculated using the MD5 hex digest. This method is now deprecated. We include both the old signature (signature) and the new signature (signature_hmac_sha_256) for backward compatibility. Ignore signature. The MD5 signature will be removed in a future update.

Protect your site’s shared key as you would your password. A compromised shared key could allow malicious actors to generate falsified webhooks that pass signature verification.

Webhook Signature

Webhooks are signed using an HMAC-SHA-256 hex digest of the raw HTTP body of the webhook post, with your shared key as the secret. In Ruby:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), site.shared_key, webhook.body)

For example, if your shared key is 123 and the webhook request body is payload[chargify]=testing&event=test, then the signature_hmac_sha_256 is: 19826d51b9f866b26eda1f154de192593360f8d0bcb63df8a28540a5dcf733f1.

This signature is sent with the webhook in the header X-Chargify-Webhook-Signature-Hmac-Sha-256. Alternatively, it can be appended to your URL as a query parameter using {signature_hmac_sha_256}.

For instance, providing the URL http://example.com/?signature_hmac_sha_256={signature_hmac_sha_256} would result in the following webhook being posted:

http://example.com/?signature_hmac_sha_256=19826d51b9f866b26eda1f154de192593360f8d0bcb63df8a28540a5dcf733f1

Payments - Direct Debit

There are three webhooks in Advanced Billing that are related to payments status change:

• direct_debit_payment_pending - This webhook is sent when payment was created in Stripe (payment is waiting for being processes).
• direct_debit_payment_paid_out - This webhook is sent when payment was successfully processed in Stripe.
• direct_debit_payment_rejected - This webhook is sent when payment was rejected in Stripe (e.g. insufficient funds on the customer account).

Finding Your Site Shared Key

Your site’s shared key is automatically generated when the site is created. You can view or update it by selecting “Edit current Site” from the Site dropdown menu in the utility bar.

Configuring Webhooks

Configure webhooks in the Settings tab for each site. Enable webhooks, provide a target URL, and subscribe to specific events. Note: the target URL can only use ports 80 and 443, specified via http or https.

Webhook Testing

Use the Webhook Testing tab (located under Tools) to send test webhook data to any configured endpoint. This feature ensures the operational status of your endpoint, though the payload may not match production webhooks. Test webhooks include the following payload:

id=123456&event=test&payload[chargify]=testing

For comprehensive testing, use a sandbox account to create test subscriptions and perform actions that trigger live webhooks. Refer to the Payload Examples article for full examples.

Webhook Metadata

Webhook records include metadata about their acceptance or rejection by your application, as well as details about errors encountered during delivery attempts. Metadata attributes include:

• id: Unique identifier for the webhook, consistent across retries/replays.
• successful: Boolean indicating whether the webhook was accepted on its last attempt.
• created_at: Timestamp for when the webhook was created.
• accepted_at: Timestamp for when the webhook was successfully accepted.
• last_sent_at: Timestamp for the most recent delivery attempt.
• last_error_at: Timestamp for the last failed delivery attempt.
• last_error: Description of the error from the last failed attempt.

Webhooks retain their event and payload data. Refer to the Webhook API for detailed attribute documentation.

Once a webhook is accepted, the accepted_at timestamp will be filled. This timestamp can be viewed via the webhooks API or in the webhooks panel, if available for your plan.

Population of Webhook Data

Each event in Advanced Billing generates a unique webhook payload containing relevant subscriber data. However, not all values may be populated in the payload. Use discretion to determine whether the data is available and how to handle missing information.

For instance, the reason_code data is not delivered in a signup_success webhook. Future updates to this documentation will provide additional examples of nil results in payload data.