Add to Chrome
x
Add to Chrome
ChargeDesk offers webhooks which can be used to receive notifications about events occurring on your account. Each time an event occurs in your account, ChargeDesk will send a notification to any webhooks your setup in your ChargeDesk account. There are many different kinds of events you can receive notifications about.
Webhooks can be configured by an administrator from Setup > API after logging into your ChargeDesk account. Each webhook you setup can either receive all possible notification events, or a subset of events. The URL for the webhook should be a valid, publicly accessible URL.
You can test your webhooks by using a service such as https://webhook.site/ to generate a temporary testing URL.
A list of all possible webhook events can be found below;
To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code (e.g. 200). This will let ChargeDesk know that the webhook has been received and no further delivery attempts will be made for that notification.
Any other response codes including 3xx will indicate to ChargeDesk that the webhook was not successfully received. If your endpoint takes more than 30 seconds to respond, it will also be considered failed. Upon failure, the webhook event will be retried once every hour for up to 3 days until a successful response code is received. If a webhooks fails for a large percentage of requests for more than 1 week, it may be disabled and further events will not be sent. You can also send a 410 response code to indicate you do not want to receive any further requests and ChargeDesk will disable the webhook immediately.
The following are example webhook payloads for different types of events.
Charge Notification
{
"event_id": "event-example-3DvJpmYL84TVhXVy0d",
"created": 1713525233,
"class": "charge",
"event": "charge_paid",
"data": {
"charge": {
"amount": "34.00",
"amount_refunded": "0.00",
"currency": "USD",
"payment_method": "Credit",
"payment_method_brand": "Visa",
"gateway_id": "",
"charge_id": "example-TapaJ9kT574XetzG98x3wikx",
"customer_id": "cus-example-2Y9PR2ytPn",
"product_id": "prod-example-1hFSMsEFKy",
"subscription_id": "sub-example-3JV42s6onS",
"transaction_id": "transaction-example-0OvvqwAEw5",
"customer_name": "Jane Customer",
"customer_email": "jane@example.com",
"customer_username": "janecustomer",
"customer_country": "US",
"description": "An example charge",
"last_4_digits": "1234",
"occurred": 1713525233,
"object": "charge",
"amount_with_commas": "34.00",
"amount_refunded_formatted": "$0.00 USD",
"amount_symbol": "$",
"amount_formatted": "$34.00 USD",
"is_paid": true,
"status": "paid",
"status_text": "paid",
"support_email": "company-example+example-TapaJ9kT574XetzG98x3wikx@chargedesk.com",
"support_url": "https://chargedesk.com/company-example/example-TapaJ9kT574XetzG98x3wikx",
"manage_url": "https://chargedesk.com/manage/company-example/charges/example-TapaJ9kT574XetzG98x3wikx",
"invoice_url": "https://chargedesk.com/company-example/example-TapaJ9kT574XetzG98x3wikx/invoice",
"invoice_download_url": "https://chargedesk.com/company-example/example-TapaJ9kT574XetzG98x3wikx/invoice/download",
"customer_phone": null,
"methods_supported": [
"edit",
"remind",
"email"
],
"methods_active": [
"email"
],
"occurred_relative": "moments ago",
"occurred_formatted": "moments ago",
"payment_method_describe": "Visa credit card",
"added_tax": "0.00",
"invoice_company": null,
"company": "company-example",
"metadata": {
"example_key": "Example charge metadata"
},
"logs": [],
"gateway_url": "",
"sent_invoice": "",
"sent_invoice_reminder": "",
"refunded_at_formatted": "",
"product_desc": "",
"name_email": "receipt",
"email_last_sent": 0,
"name_send_email": "Send Receipt"
}
}
}Customer Notification
{
"event_id": "event-example-6vseMIpRaAhULgznwA",
"created": 1713525233,
"class": "customer",
"event": "customer_first_paid",
"data": {
"customer": {
"customer_id": "cus-example-IetbkKBp9P",
"gateway_id": "",
"name": "Jane Customer",
"email": "jane@example.com",
"username": "janecustomer",
"description": "An example customer",
"phone": "+1 555-555-5555",
"company": "company-example",
"website": "https://example.com",
"country": "US",
"delinquent": 0,
"edited": 0,
"tax_number": "123456789",
"tax_number_abr": "VAT",
"billing_address": "123 Example Street\nExample City\nExample State, United States, 90000",
"shipping_address": "",
"invoice_details": "",
"object": "customer",
"charges": 0,
"first_seen": 1713525233,
"subscriptions": [],
"readable_country": "United States",
"methods_supported": [
"invoice",
"edit"
],
"methods_active": [
"invoice",
"edit"
],
"customer_company": "Example Company LTD",
"metadata": {
"example_key": "Example customer metadata"
},
"logs": [],
"items": [],
"first_name": "Jane",
"manage_url": "https://chargedesk.com/manage/company-example/customers/cus-example-IetbkKBp9P",
"gateway_url": ""
}
}
}Subscription Notification
{
"event_id": "event-example-cRoIusa6SmZGGurvFJ",
"created": 1713525233,
"class": "subscription",
"event": "subscription_upgraded",
"data": {
"subscription": {
"subscription_id": "sub-example-nx1KOjSITK",
"customer_id": "cus-example-3osllrJcvl",
"product_id": "prod-example-Dw0Il0lj9J",
"amount": "34.00",
"currency": "USD",
"gateway_id": "",
"interval": "month",
"interval_count": 1,
"charges": 1,
"quantity": 2,
"current_period_start": 1713525233,
"current_period_end": 1716154976,
"trial_start": 0,
"trial_end": 1714734833,
"ended_at": 0,
"canceled_at": 0,
"has_items": 0,
"billing_cycles_total": 0,
"billing_cycles_current": 1,
"trial_period_days": 14,
"setup_amount": 10,
"object": "subscription",
"amount_formatted": "2x $34.00 USD",
"amount_symbol": "$",
"status": "active",
"status_text": "Active",
"first_seen": 1713525233,
"methods_supported": [
"edit"
],
"methods_active": [
"edit"
],
"readable_interval": "Monthly",
"product_desc": "",
"company": "company-example",
"logs": [],
"items": [],
"metadata": {
"example_key": "Example subscription metadata"
},
"manage_url": "https://chargedesk.com/manage/company-example/subscriptions/sub-example-nx1KOjSITK",
"gateway_url": ""
}
}
}Agent Log Notification
{
"event_id": "event-example-pq2y9ZOVqGnvIcQ1Sp",
"created": 1713525233,
"class": "agent_log",
"event": "agent_log_new",
"data": {
"agent_log": {
"source": "web",
"object_type": "charge",
"object_id": "example-4muvYMyUSUrNfjEoviZaYQv5",
"action_type": "refund",
"action_reason": "Example refund",
"event": "charge-refund",
"ip": "1.2.3.4",
"description": "Charge Refunded",
"sub_description": "",
"occurred": 1713525233,
"context": null,
"params": null,
"company": "company-example",
"action_params": false
},
"charge": {
"amount": "34.00",
"amount_refunded": "21.00",
"currency": "USD",
"payment_method": "Credit",
"payment_method_brand": "Visa",
"gateway_id": "",
"charge_id": "example-4muvYMyUSUrNfjEoviZaYQv5",
"customer_id": "cus-example-EGBsqjX1fG",
"product_id": "prod-example-C52cJREHGd",
"subscription_id": "sub-example-1Qp0RktrOV",
"transaction_id": "transaction-example-ZN8wZmCVcf",
"customer_name": "Jane Customer",
"customer_email": "jane@example.com",
"customer_username": "janecustomer",
"customer_country": "US",
"description": "An example charge",
"last_4_digits": "1234",
"occurred": 1713525233,
"object": "charge",
"amount_with_commas": "34.00",
"amount_refunded_formatted": "$21.00 USD",
"amount_symbol": "$",
"amount_formatted": "$34.00 USD",
"is_paid": true,
"status": "partially refunded",
"status_text": "partially refunded",
"support_email": "company-example+example-4muvYMyUSUrNfjEoviZaYQv5@chargedesk.com",
"support_url": "https://chargedesk.com/company-example/example-4muvYMyUSUrNfjEoviZaYQv5",
"manage_url": "https://chargedesk.com/manage/company-example/charges/example-4muvYMyUSUrNfjEoviZaYQv5",
"invoice_url": "https://chargedesk.com/company-example/example-4muvYMyUSUrNfjEoviZaYQv5/invoice",
"invoice_download_url": "https://chargedesk.com/company-example/example-4muvYMyUSUrNfjEoviZaYQv5/invoice/download",
"customer_phone": null,
"methods_supported": [
"edit",
"remind",
"email"
],
"methods_active": [
"email"
],
"occurred_relative": "moments ago",
"occurred_formatted": "moments ago",
"payment_method_describe": "Visa credit card",
"added_tax": "0.00",
"invoice_company": null,
"company": "company-example",
"metadata": {
"example_key": "Example charge metadata"
},
"logs": [],
"gateway_url": "",
"sent_invoice": "",
"sent_invoice_reminder": "",
"refunded_at_formatted": "",
"product_desc": "",
"name_email": "refund notification",
"email_last_sent": 0,
"name_send_email": "Send Refund Notification"
}
}
}The charge_request_paid and charge_request events also include the following additional fields;
{
// ...
"data": {
"charge": {
// ...
"source_ticket": "1234", // The ID of the helpdesk ticket where the request was created (where available)
"source_customer": "5678", // The ID of the helpdesk customer where the request was created (where available)
"source_url": "https://helpdesk.com/ticket/1234", // The URL of the page where the request was created
}
}
}ChargeDesk includes information in the header of webhook requests which you should use to verify that the notification you receive has actually come from ChargeDesk.
There are 2 headers which ChargeDesk includes in webhook requests which are needed for verification; ChargeDesk-Signature-Time and ChargeDesk-Signature
The ChargeDesk-Signature-Time header allows you to verify that the webhook was recently sent and allows you to prevent replay attacks. This is timestamp showing seconds since epoch (unix time). We recommend verifying this time is less than 5 minutes old.
The ChargeDesk-Signature signs the timestamp along with the entire request using a unique secret key for your webhook. You can find your secret webhook key by clicking the "Edit webhook" link under Setup > API. This key is unique for each webhook you add.
To verify the signature, you should concatenate;
The following is example PHP code which shows verification process.
$secret_key = "unique_secret_key_for_your_webhook";
$body = @file_get_contents('php://input');
$timestamp = intval($_SERVER['HTTP_CHARGEDESK_SIGNATURE_TIME']);
$signature = $_SERVER['HTTP_CHARGEDESK_SIGNATURE'];
// Verify request format
if(!$body || !$timestamp || !$signature) {
header("HTTP/1.1 406 Not Acceptable");
die("Invalid request");
}
// Verify that the timestamp is recent enough
if (abs(time() - $timestamp) > 300) {
header("HTTP/1.1 406 Not Acceptable");
die("Invalid timestamp");
}
// Verify the signature is valid
$signed_payload = $timestamp.".".$body;
if(hash_hmac('sha256', $signed_payload, $secret_key) !== $signature) {
header("HTTP/1.1 406 Not Acceptable");
die("Invalid signature");
}
// Parse the JSON body
$payload = json_decode((string)$body, true);
// You can now safely use the payload
print "Received event type ".$payload['event'];