Receive webhooks

DCDial can notify your server when something happens, instead of you polling the API.

Set up

1. In the DCDial app, open your account settings and add your webhook URL.
2. Choose the format: JSON or XML.
3. DCDial sends an HTTP POST to that URL for each event. Respond with any 2xx status.

Tip

Use an https:// URL that is hard to guess, and check that the fields in each event match an account you know before acting on it.

Transaction webhook

Sent for each payment transaction, including scheduled payments on an agreement.

Field	Type	Description
transaction_id	string	Gateway transaction ID
amount	decimal	Amount of this transaction
first_name	string	Account holder’s first name
last_name	string	Account holder’s last name
phone_number	number	Account holder’s phone number
card_last_4_digits	number	Last four digits of the card
invoice	number	DCDial invoice ID
is_subscription	Y | N	Part of a recurring schedule
customerid	number	DCDial customer ID
gateway_error	string	Gateway error message, if the payment failed
MerchantName	string	Merchant name
AccountID	string	Your account reference
StartDate	date-time	Agreement start date
PaymentFrequency	string	Agreement frequency
PaymentAmount	decimal	Scheduled payment amount
TotalPayments	number	Payments in the agreement
RemainingPayments	number	Payments left
currunt_billing_count	number	Number of this payment in the schedule (field name as sent)
exclude_holidays	Y | N	Whether holidays are skipped
AgreementID	number	Payment agreement ID
PaymentEndDate	date	Last scheduled payment date
CurrentRecurringPaymentCount	string	Recurring payment count
apiKey	string	Your company’s API key, to confirm the event is for you
AuthId	string	Gateway authorization ID

Example (JSON)

{
  "transaction_id": "ch_3Q8x2e",
  "amount": "150.00",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "5550100123",
  "card_last_4_digits": "4242",
  "invoice": "88812",
  "is_subscription": "Y",
  "gateway_error": "",
  "AccountID": "ACC-10045",
  "PaymentFrequency": "monthly",
  "PaymentAmount": "150.00",
  "TotalPayments": "6",
  "RemainingPayments": "5",
  "AgreementID": "5521"
}

SMS webhook

Sent when an account holder replies to one of your numbers.

Field	Type	Description
caller_id	string	Your number that received the reply
phone_number	number	Account holder’s phone number
message_time	date-time	When the reply arrived
company_id	number	Your DCDial company ID
customer_reply	text	The message text