Webhooks

Webhooks provide an effective way to keep you up-to-date on all transaction events in real time. Transaction events include actions like authorizations, payments, refunds and more.

Whenever one of these events occurs, the webhook will provide you with basic details about the event, such as the price, shipping address details, payment method, and shopper information.

Common Use Cases

Here are some ways you might use webhooks:

Make sure your accounting records are updated when a payment is made
Take action when a chargeback is processed
Send a subscription reminder email to a customer when their subscription is due for renewal
Update your customer database when a subscription is processed

How and when BlueSnap sends Webhooks

Webhooks are automatically transmitted via an HTTP POST request to a unique URL on your site's server, which you will define. Webhooks are triggered by an event such as an authorization, payment acceptance, or refund confirmation and are sent as soon as the event is complete. Refer to Webhook FAQs.

Webhooks in the Merchant Portal

To enable webhooks, you need to set up a server and URL on your side and then configure webhooks in your BlueSnap account. Refer to Setting up Webhooks.

Webhooks APIs

We also offer APIs to retrieve webhook configuration information, enable/disable webhook, or delete all webhook configurations for a user.

Request Content

Property	Type	Required
`ipnDestinations`	object	required
`ipnUrl`	string	required
`ensureNotificationReceipt`	string	required
`receiveAffiliateNotifications`	string	required

Retrieve webhook Configuration

Retrieve the current webhook settings using this request.

curl -L -X GET 'https://sandbox.bluesnap.com/services/2/notification-config/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'bluesnap-version: 2.0' \
-H 'Authorization: Basic QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkhvYmJpdHkyMSE=' \

Enable and Disable Webhooks

Use this request to enable or disable specific webhook types, as well as the ensureNotificationReceipt and receiveAffiliateNotifications settings.

In the body of the request, include JSON or XML representing your desired notification configuration for the authorized user. You can set each webhook type to true to enable or false to disable. Fields that are not explicitly sent in the request body will be set to false by default.

Note that the ipnURL field is required. You may use a third party webhook site like https://webhook.site/ to generate an ipnURL.

curl -L -X POST 'https://sandbox.bluesnap.com/services/2/notification-config/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkhvYmJpdHkyMSE=' \
-d '
{
    "ipnDestinations": [
        {
            "ipnUrl": "https://webhook.site/2560e9b0-c46c-4a48-9333-0f9108e74348",
            "sendAuthOnly": true,
            "sendCancellation": true,
            "sendCancelOnRenewal": true,
            "sendCharge": true,
            "sendChargeback": true,
            "sendChargebackStatusChanged": true,
            "sendContractChange": false,
            "sendCancellationRefund": true,
            "sendFailedPayoutTransfer": false,
            "sendSubscriptionReminder": true,
            "sendDecline": true,
            "sendRefund": true,
            "sendRecurring": false,
            "sendCcFailure": true,
            "sendSubCcFailure": true,
            "sendUnderVendorReview": true,
            "sendPaymentUpdate": true,
            "sendPaymentUpdateFailure": true,
            "sendAccountUpdater": true,
            "sendPayout": true,
            "sendVendorStatusChanged": true,
            "sendFraudDecline": true,
            "sendChargePending": true,
            "sendShopperDeleted": true,
            "sendVendorReportAvailable": true,
            "sendMerchantOnboarded": true,
            "sendOfflineOrder": true,
            "sendCcStatusChanged": false
        }
    ],
    "ensureNotificationReceipt": false,
    "receiveAffiliateNotifications": true
}'

Delete All Webhook Configurations

Use this request to remove all webhook destinations and configurations associated with the authorized user.

curl -L -X DELETE 'https://sandbox.bluesnap.com/services/2/notification-config/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'bluesnap-version: 2.0' \
-H 'Authorization: Basic QVBJXzE2MTk2MjgyMzU0ODkyMDM5MTMzODc0OkhvYmJpdHkyMSE=' \

Available Webhook Types

BlueSnap provides webhooks to all merchants for various event types, such as a charge, authorization only, an offline order or failed credit card charge. See Webhooks Name Reference for a complete list of available webhooks and detailed information about each one.

For details about all webhook parameters, Refer to Webhooks Parameter Reference.

Example Webhook

A webhook is a long string of text with fields and attributes that contain information about the transaction. For example:

invoiceCountry=US&invoiceZipCode=&invoiceFirstName=Joe&invoiceFaxNumber=&invoiceState=OR&invoiceAddress2=&invoiceEmail=emil.ray%40bluesnap.com&invoiceLastName=Shopper&invoiceAddress1=&invoiceCompany=&invoiceCity=&invoiceExtension=&invoiceMobilePhone=&invoiceWorkPhone=&invoiceTitle=&lastName=Shopper&country=US&zipCode=&extension=&address2=&city=&address1=&homePhone=&title=&accountId=20626979&firstName=Joe&mobilePhone=&faxNumber=&company=&workPhone=&state=OR&email=emil.ray%40bluesnap.com&username=1447774446472887319554743963741&shippingCity=&shippingLastName=Shopper&shippingCountry=US&shippingZipCode=&shippingMethod=&shippingFirstName=Joe&shippingState=OR&shippingAddress2=&shippingAddress1=&overridePrice=0.00&invoiceAmount=30.00&language=ENGLISH&creditCardType=VISA&invoiceAmountUSD=30.00&templateId=91&productName=My+Awesome+Game&creditCardExpDate=1%2F2016&contractOwner=500801&referenceNumber=1011310133&contractName=Nintendo+Version&currency=USD&invoiceInfoURL=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DDB24C79E3E449AB09A1936EF6F020625%26acd%3D80FD091BA5366B75&remoteAddress=50.207.189.243&contractChargePrice=30.00&quantity=1&productId=404141&invoiceChargeCurrency=USD&cardSubType=CREDIT&invoiceChargeAmount=30.00&referrer=&contractPrice=30.00&creditCardLastFourDigits=1111&testMode=N&contractId=2269035&addCD=N&untilDate=11%2F17%2F2015+07%3A34+AM&paymentMethod=CC&paymentType=CC&invoiceLocalAmount=30.00&invoiceURL=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Fshow_invoice.jsp%3Fref%3DDB24C79E3E449AB09A1936EF6F020625&shopperOrderUrl=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DDB24C79E3E449AB09A1936EF6F020625%26acd%3D80FD091BA5366B75&originalRequestUrl=&contractLocalPrice=30.00&shopperAdminUrl=https%3A%2F%2Fsandbox.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DDB24C79E3E449AB09A1936EF6F020625%26acd%3D80FD091BA5366B75&invoiceLocalCurrency=USD&recurringDisclaimer=N&targetBalance=BLUESNAP_ACCOUNT&promoteContractsNum=0&EDWPeriod=&EDWSurcharge=&EDWAmountUSD=&EDWContractId=&EDWSurchargeUSD=&EDWAmount=&vatId=&taxAmountUSD=0.00&taxRate=&taxChargeAmount=0.00&authKey=&transactionType=CHARGE&bluesnapNode=99&plimusNode=99&couponCode=&licenseKey=Licensing+information+will+be+sent+to+you+shortly.&cvvSent=Y&avsSent=N&cvvResponse=Not+processed+&avsResponse=Issuer+unavailable+or+AVS+not+supported+%28US+Issuer%29+&transactionDate=11%2F17%2F2015+07%3A34+AM

lastName=Doe&country=US&zipCode=30328&extension=52&address2=&city=Atlanta&address1=760+MT+VERNON+HIGHWAY+NE+%2CATLANTA+GA+30328&homePhone=&title=&accountId=19589706&firstName=Jhone&mobilePhone=&faxNumber=&company=&workPhone=0523584124&state=AL&email=jhonedoe%40gmail.com&username=1471869314641&invoiceCountry=US&invoiceZipCode=30328&invoiceFirstName=Shaul+Cohen+OR+Alon&invoiceFaxNumber=&invoiceState=AL&invoiceAddress2=&invoiceEmail=jhonedoe%40gmail.com&invoiceLastName=Yosef&invoiceAddress1=760+MT+VERNON+HIGHWAY+NE+%2CATLANTA+GA+30328&invoiceCompany=&invoiceCity=Atlanta&invoiceExtension=52&invoiceMobilePhone=&invoiceWorkPhone=0523584124&invoiceTitle=&shippingCity=Atlanta&shippingLastName=Yosef&shippingCountry=US&shippingZipCode=30328&shippingMethod=&shippingFirstName=Jhone&shippingState=AL&shippingAddress2=&shippingAddress1=760+MT+VERNON+HIGHWAY+NE+%2CATLANTA+GA+30328&invoiceAmount=2.00&language=ENGLISH&creditCardType=VISA&cardSubType=DEBIT&cardCategory=PEONY&invoiceAmountUSD=2.00&productName=testProduct&paymentType=&creditCardExpDate=&contractOwner=399928&referenceNumber=38528358&contractName=Subscription+contract+2&currency=USD&cancelReason=test&invoiceInfoURL=https%3A%2F%2Fshoppers.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DEBBE554ECE528D63%26acd%3DEBEDCB01BBF0320D&remoteAddress=0%3A0%3A0%3A0%3A0%3A0%3A0%3A1&quantity=1&productId=310592&invoiceChargeCurrency=USD&invoiceChargeAmount=2.00&originalRefNum=38528358&transactionType=CANCELLATION&referrer=&creditCardLastFourDigits=&testMode=N&contractId=2186556&paymentMethod=&subscriptionId=39546714&addCD=N&untilDate=08%2F29%2F2016+06%3A06+AM&authKey=4df72f8c802a6caf5b0e3e4439cfb891&targetBalance=BLUESNAP_ACCOUNT&taxAmountUSD=0.00&taxRate=&taxChargeAmount=0.00&vatId=&Color=Green&cancelledContractId=2186556&shippingMethod=&shopperOrderUrl=https%3A%2F%2Fshoppers.bluesnap.com%2Fjsp%2Forder_locator_info.jsp%3FrefId%3DEBBE554ECE528D63%26acd%3DEBEDCB01BBF0320D&templateId=2&licenseKey=&promoteContractsNum=0&bluesnapNode=1&plimusNode=1&couponCode=&transactionDate=08%2F22%2F2016+04%3A10+PM&merchantTransactionId=&vendorId=11111&vendorName=vendor+name+test