Welcome to Xendit’s latest documentation. For legacy content, access the previous documentation here or the previous API reference here.

Set Webhook URL

Prev
Post
/callback_urls/{type}

The Set Webhook URLs API allows you to set your account and sub-accounts' Webhook URLs. The following can be used in the :type path parameters:

Money-In

  • invoice: Xendit notifies your system when Invoice has been paid or expired.
  • fva_status: Xendit notifies your system when Virtual Account has been created or updated successfully. Support: Indonesia only 🇲🇨
  • fva_paid: Xendit notifies your system when Virtual Account has been paid successfully. Support: Indonesia only 🇲🇨
  • ro_fpc_paid: Xendit notifies your system when Retail Outlet payment code (Alfamart/Indomaret) in Indonesia has been paid successfully. Support: Indonesia only 🇲🇨
  • regional_ro_paid: Xendit notifies your system when Over-the-Counter payment code (7 Eleven, Cebuana, ECPay) in Philippines has been paid successfully. Support: Philippines only 🇵🇭
  • ewallet: New eWallet type to receive charge and other eWallet events across eWallets channels from /ewallets/charges API.
  • payment_method: Xendit notifies your system when payment method is expiring and/or has expired. Payment Method is a mandatory step to abstract Debit Card/Bank Account for Direct Debit transactions.
  • payment_method_v2: Xendit notifies your system when payment method V2 is expiring and/or has activated or expired. Learn more about Payment Method V2 here.
  • direct_debit: A Direct Debit payment event will be sent to your system for any successful transactions. Use direct_debit type to receive Direct Debit payment event via webhook.
  • qr_code: Xendit notifies your system when QR payment has been made or QR refund has been completed. This field is only supported for qr_codes API version 2022-07-31.
  • recurring: Xendit notifies your system when Subscription plan has been activated/inactivated, cycle created/succeeded/retrying/failed, or force attempt failed.
  • payment_succeeded: Xendit notifies your system when a payment has been successfully confirmed or received from the partner channel (Only for payments initiated via new Payments API). Support: All businesses
  • payment_awaiting_capture: Xendit notifies your system when a payment request with capture_method set to MANUAL has been intialized and a call to the Payment Capture API needed to complete the payment. Support: All businesses
  • payment_pending: Xendit notifies your system when a payment is being processed by the partner channel awaiting for the terminal status of it (Only for payments initiated via new Payments API). Support: All businesses
  • payment_failed: Xendit notifies your system when a pending payment has failed (Only for payments initiated via new Payments API). Support: All businesses
  • capture_succeeded: Xendit notifies your system when a manual capture via the Payment Capture API has succeeded. Support: All businesses
  • capture_failed: Xendit notifies your system when a manual capture via the Payment Capture API has Failed. Support: All businesses
  • payment_request_completed: Xendit notifies your system when a Direct Debit or E-Wallet payment request has succeeded or failed. Please Note that this is for the Payment Request API only. Make sure that other payment callbacks for Direct Debit or E-wallet are not set to prevent duplication. Support: Thailand 🇹🇭 and Malaysia 🇲🇾 only

Money-Out

  • disbursement: Xendit notifies your system when disbursement has been executed successfully by Xendit, either with COMPLETED or FAILED status. Support: Indonesia only 🇲🇨

  • ph_disbursement: Xendit notifies your system when disbursement has been executed successfully by Xendit, either with COMPLETED or FAILED status. Support: Philippines only 🇵🇭

  • batch_disbursement: Xendit notifies your system when Batch Disbursement has been executed successfully by Xendit. Support: Indonesia only 🇲🇨

  • payout: Xendit notifies your system upon failed and successful payouts. Learn more about Payouts V2 webhooks here. Others

  • report: Xendit notifies your system to send the report to the specified URLs. Support: All businesses

Security
HTTP
Type basic
Header parameters
for-user-id
string
Example5cafeb170a2b18519b1b8761
Path parameters
type
stringRequired

The type of Webhook URL you want to set

Valid values[ "invoice", "fva_status", "fva_paid", "ro_fpc_paid", "regional_ro_paid", "ewallet", "payment_method", "payment_method_v2", "direct_debit", "qr_code", "recurring", "disbursement", "ph_disbursement", "batch_disbursement", "report", "payment_succeeded", "payment_awaiting_capture", "payment_pending", "payment_failed", "capture_succeeded", "capture_failed", "payment_request_completed" ]
Body parameters
{
  "url": "https://www.xendit.co/webhook_catcher"
}
object
url
string Required

The URL of your server that you want to receive our Webhooks

Min length1
Responses
200
{
  "status": "SUCCESSFUL",
  "user_id": "5e6b30d967627b957de8c123",
  "url": "https://www.xendit.co/webhook_catcher",
  "environment": "TEST",
  "callback_token": "66a6680348e1c33ed2b9053a8eb9291b9e2230ff4f4d3057c9f4ac26405d2123"
}
object
status
string

The status of setting the Webhook URL

Valid values[ "SUCCESSFUL" ]
user_id
string

The user_id on which the Webhook URL has been set

url
string

The Webhook URL that has been set

environment
string

The environment on which the Webhook URL has been set

Valid values[ "TEST", "LIVE" ]
callback_token
string

The unique Webhook token that is attached to each sub-account. Use this to validate that a Webhook is sent from Xendit's servers.

400

Validation error

INVALID_URL_FORMAT
{
  "error_code": "INVALID_URL_FORMAT",
  "message": "You have provided an invalid URL format",
  "errors": [
    "Detailed description here"
  ]
}
object

Inputs are failing validation. The errors field contains details about which fields are violating validation.

error_code
string
Valid values[ "API_VALIDATION_ERROR", "INVALID_CONFIGURATION", "INVALID_JSON_FORMAT", "TYPE_AND_CONFIGURATION_CONFLICT", "INVALID_SOURCE_OR_DESTINATION_ERROR", "INSUFFICIENT_BALANCE", "INVALID_FEE_AMOUNT", "DUPLICATE_ERROR", "INVALID_AMOUNT", "INSUFFICIENT_ACCOUNT_HOLDER_DATA" ]
message
string
errors
Array
OneOf
string
string
object
object
404

Validation error

CALLBACK_AUTHENTICATION_TOKEN_NOT_FOUND_ERROR
{
  "error_code": "CALLBACK_AUTHENTICATION_TOKEN_NOT_FOUND_ERROR",
  "message": "No webhook verification token found for this business, please contact help@xendit.co to resolve this issue",
  "errors": [
    "Detailed description here"
  ]
}
object

The object being referenced does not exist

error_code
string
Valid values[ "DESTINATION_ACCOUNT_NOT_FOUND", "DATA_NOT_FOUND" ]
message
string
errors
Array
OneOf
string
string
object
object