Webhooks

Webhooks are a way to notify your application when an event occurs, such as a new order. They allow for deeper e-commerce integration of your shopping cart.

We will send you a POST to an URL that you can provide us in the dashboard.

Configure webhook URL

To configure this setting, log into the Snipcart dashboard, then, under the Account menu on the right, you will see Webhooks in Store configurations.

The URL that you will provide us must be an absolute URL such as https://myapplication.com/webhooks

We included some examples on how to consume Webhook requests below in this article.

Events


order.completed

It occurs when a new order has been completed successfully.

{
  "eventName": "order.completed",
  "mode": "Test",
  "createdOn": "2015-02-21T14:58:02.6738454Z",
  "content": {
    "token": "496945f9-2776-4b40-878a-d209359f90fd",
    "userId": "46351085-8207-4cb6-8a3d-ffa33929267a",
    "creationDate": "2015-02-21T14:57:12.09Z",
    "modificationDate": "2015-02-21T14:58:01.727Z",
    "completionDate": "2015-02-21T14:58:01.727Z",
    "status": "Processed",
    "paymentMethod": "CreditCard",
    "invoiceNumber": "SNIP-1351",
    "email": "geeks@snipcart.com",
    "cardHolderName": "Geeks at Snipcart",
    "billingAddressName": "Geeks at Snipcart",
    "billingAddressCompanyName": "Snipcart",
    "billingAddressAddress1": "4885 1ere Avenue",
    "billingAddressAddress2": "Suite 200",
    "billingAddressCity": "Quebec",
    "billingAddressCountry": "CA",
    "billingAddressProvince": "QC",
    "billingAddressPostalCode": "G1H2T5",
    "billingAddressPhone": "418 800 7440",
    "shippingAddressName": "Geeks at Snipcart",
    "shippingAddressCompanyName": "Snipcart",
    "shippingAddressAddress1": "4885 1ere Avenue",
    "shippingAddressAddress2": "Suite 200",
    "shippingAddressCity": "Quebec",
    "shippingAddressCountry": "CA",
    "shippingAddressProvince": "QC",
    "shippingAddressPostalCode": "G1H2T5",
    "shippingAddressPhone": "418 800 7440",
    "shippingAddressSameAsBilling": true,
    "finalGrandTotal": 39.09,
    "creditCardLast4Digits": "4242",
    "shippingFees": 10,
    "shippingMethod": "Fast custom shipping",
    "items": [{
      "uniqueId": "450c12ec-1a72-4225-8a23-b28ec8d1e2ca",
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "id": "42",
      "name": "Bacon",
      "price": 10,
      "quantity": 3,
      "url": "https://snipcart.com/",
      "weight": 20,
      "description": null,
      "image": "",
      "stackable": true,
      "duplicatable": false,
      "maxQuantity": null,
      "addedOn": "2015-02-21T14:57:17.157Z",
      "shippable": true,
      "taxable": true,
      "totalPrice": 30,
      "totalWeight": 60,
      "customFields": [{
        "name": "Size",
        "value": "Large"
      }],
      "unitPrice": 10
    }],
    "taxes": [{
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "taxName": "TPS",
      "taxRate": 0.05,
      "amount": 1.7
    },{
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "taxName": "TVQ",
      "taxRate": 0.09975,
      "amount": 3.39
    }],
    "rebateAmount": 6,
    "subtotal": 24,
    "itemsTotal": 30,
    "taxableTotal": 30,
    "grandTotal": 39.09,
    "totalWeight": 60,
    "totalRebateRate": 20,
    "discounts": [{
      "id": "e2118d1c-e5e7-43ab-9d43-ad9bd1c18a56",
      "amountSaved": 6,
      "name": "20% off",
      "combinable": true,
      "trigger": "Code",
      "code": "20_off",
      "type": "Rate",
      "rate": 20
    }],
    "willBePaidLater": false,
    "totalNumberOfItems": 0,
    "customFieldsJson": null,
    "customFields": [{
        "name": "I accept terms",
        "value": true
    }],
    "shippingEnabled": true,
    "numberOfItemsInOrder": 3,
    "paymentTransactionId": null,
    "cardType": "Visa",
    "paymentGatewayUsed": "Stripe",
    "taxesTotal": 5.09,
    "itemsCount": 3,
    "metadata": null,
    "ipAddress": "127.0.0.1"
  }
}

order.status.changed

It occurs when a new order status is updated. The content of the request will be the updated order. You will also have access to from and to properties if you need to do anything with the state change.

{
  "eventName": "order.status.changed",
  "mode": "Test",
  "createdOn": "2015-02-21T14:58:02.6738454Z",
  "from": "Processed",
  "to": "Shipped",
  "content": {
    "token": "496945f9-2776-4b40-878a-d209359f90fd",
    "userId": "46351085-8207-4cb6-8a3d-ffa33929267a",
    "creationDate": "2015-02-21T14:57:12.09Z",
    "modificationDate": "2015-02-21T14:58:01.727Z",
    "completionDate": "2015-02-21T14:58:01.727Z",
    "status": "Shipped",
    "paymentMethod": "CreditCard",
    "invoiceNumber": "SNIP-1351",
    "email": "geeks@snipcart.com",
    "cardHolderName": "Geeks at Snipcart",
    "billingAddressName": "Geeks at Snipcart",
    "billingAddressCompanyName": "Snipcart",
    "billingAddressAddress1": "4885 1ere Avenue",
    "billingAddressAddress2": "Suite 200",
    "billingAddressCity": "Quebec",
    "billingAddressCountry": "CA",
    "billingAddressProvince": "QC",
    "billingAddressPostalCode": "G1H2T5",
    "billingAddressPhone": "418 800 7440",
    "shippingAddressName": "Geeks at Snipcart",
    "shippingAddressCompanyName": "Snipcart",
    "shippingAddressAddress1": "4885 1ere Avenue",
    "shippingAddressAddress2": "Suite 200",
    "shippingAddressCity": "Quebec",
    "shippingAddressCountry": "CA",
    "shippingAddressProvince": "QC",
    "shippingAddressPostalCode": "G1H2T5",
    "shippingAddressPhone": "418 800 7440",
    "shippingAddressSameAsBilling": true,
    "finalGrandTotal": 39.09,
    "creditCardLast4Digits": "4242",
    "shippingFees": 10,
    "shippingMethod": "Fast custom shipping",
    "items": [{
      "uniqueId": "450c12ec-1a72-4225-8a23-b28ec8d1e2ca",
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "id": "42",
      "name": "Bacon",
      "price": 10,
      "quantity": 3,
      "url": "https://snipcart.com/",
      "weight": 20,
      "description": null,
      "image": "",
      "stackable": true,
      "duplicatable": false,
      "maxQuantity": null,
      "addedOn": "2015-02-21T14:57:17.157Z",
      "shippable": true,
      "taxable": true,
      "totalPrice": 30,
      "totalWeight": 60,
      "customFields": [{
        "name": "Size",
        "value": "Large"
      }],
      "unitPrice": 10
    }],
    "taxes": [{
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "taxName": "TPS",
      "taxRate": 0.05,
      "amount": 1.7
    },{
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "taxName": "TVQ",
      "taxRate": 0.09975,
      "amount": 3.39
    }],
    "rebateAmount": 6,
    "subtotal": 24,
    "itemsTotal": 30,
    "taxableTotal": 30,
    "grandTotal": 39.09,
    "totalWeight": 60,
    "totalRebateRate": 20,
    "discounts": [{
      "id": "e2118d1c-e5e7-43ab-9d43-ad9bd1c18a56",
      "amountSaved": 6,
      "name": "20% off",
      "combinable": true,
      "trigger": "Code",
      "code": "20_off",
      "type": "Rate",
      "rate": 20
    }],
    "willBePaidLater": false,
    "totalNumberOfItems": 0,
    "customFieldsJson": null,
    "customFields": [{
        "name": "I accept terms",
        "value": true
    }],
    "shippingEnabled": true,
    "numberOfItemsInOrder": 3,
    "paymentTransactionId": null,
    "cardType": "Visa",
    "paymentGatewayUsed": "Stripe",
    "taxesTotal": 5.09,
    "itemsCount": 3,
    "metadata": null
  }
}

order.trackingNumber.changed

This event will be trigerred whenever an order tracking number has changed.

{
  "trackingNumber": "TRACK-123",
  "trackingUrl": "http://track.com/123",
  "eventName": "order.trackingNumber.changed",
  "mode": "Live",
  "createdOn": "2016-08-03T15:20:40.6267006Z",
  "content": {
    "token": "496945f9-2776-4b40-878a-d209359f90fd",
    "userId": "46351085-8207-4cb6-8a3d-ffa33929267a",
    "creationDate": "2015-02-21T14:57:12.09Z",
    "modificationDate": "2015-02-21T14:58:01.727Z",
    "completionDate": "2015-02-21T14:58:01.727Z",
    "status": "Shipped",
    "paymentMethod": "CreditCard",
    "invoiceNumber": "SNIP-1351",
    "email": "geeks@snipcart.com",
    "cardHolderName": "Geeks at Snipcart",
    "billingAddressName": "Geeks at Snipcart",
    "billingAddressCompanyName": "Snipcart",
    "billingAddressAddress1": "4885 1ere Avenue",
    "billingAddressAddress2": "Suite 200",
    "billingAddressCity": "Quebec",
    "billingAddressCountry": "CA",
    "billingAddressProvince": "QC",
    "billingAddressPostalCode": "G1H2T5",
    "billingAddressPhone": "418 800 7440",
    "shippingAddressName": "Geeks at Snipcart",
    "shippingAddressCompanyName": "Snipcart",
    "shippingAddressAddress1": "4885 1ere Avenue",
    "shippingAddressAddress2": "Suite 200",
    "shippingAddressCity": "Quebec",
    "shippingAddressCountry": "CA",
    "shippingAddressProvince": "QC",
    "shippingAddressPostalCode": "G1H2T5",
    "shippingAddressPhone": "418 800 7440",
    "shippingAddressSameAsBilling": true,
    "finalGrandTotal": 39.09,
    "creditCardLast4Digits": "4242",
    "shippingFees": 10,
    "shippingMethod": "Fast custom shipping",
    "items": [{
      "uniqueId": "450c12ec-1a72-4225-8a23-b28ec8d1e2ca",
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "id": "42",
      "name": "Bacon",
      "price": 10,
      "quantity": 3,
      "url": "https://snipcart.com/",
      "weight": 20,
      "description": null,
      "image": "",
      "stackable": true,
      "duplicatable": false,
      "maxQuantity": null,
      "addedOn": "2015-02-21T14:57:17.157Z",
      "shippable": true,
      "taxable": true,
      "totalPrice": 30,
      "totalWeight": 60,
      "customFields": [{
        "name": "Size",
        "value": "Large"
      }],
      "unitPrice": 10
    }],
    "taxes": [{
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "taxName": "TPS",
      "taxRate": 0.05,
      "amount": 1.7
    },{
      "token": "496945f9-2776-4b40-878a-d209359f90fd",
      "taxName": "TVQ",
      "taxRate": 0.09975,
      "amount": 3.39
    }],
    "rebateAmount": 6,
    "subtotal": 24,
    "itemsTotal": 30,
    "taxableTotal": 30,
    "grandTotal": 39.09,
    "totalWeight": 60,
    "totalRebateRate": 20,
    "discounts": [{
      "id": "e2118d1c-e5e7-43ab-9d43-ad9bd1c18a56",
      "amountSaved": 6,
      "name": "20% off",
      "combinable": true,
      "trigger": "Code",
      "code": "20_off",
      "type": "Rate",
      "rate": 20
    }],
    "willBePaidLater": false,
    "totalNumberOfItems": 0,
    "customFieldsJson": null,
    "customFields": [{
        "name": "I accept terms",
        "value": true
    }],
    "shippingEnabled": true,
    "numberOfItemsInOrder": 3,
    "paymentTransactionId": null,
    "cardType": "Visa",
    "paymentGatewayUsed": "Stripe",
    "taxesTotal": 5.09,
    "itemsCount": 3,
    "metadata": null,
    "trackingNumber": "TRACK-123",
    "trackingUrl": "http://track.com/123"
  }
}

subscription.created

It occurs when a customer subscribes to a plan.

{
    "eventName": "subscription.created",
    "mode": "Live",
    "createdOn": "2016-07-18T20:48:53.3420632Z",
    "content": {
        "plan": {
            "subscriptionId": "fef13e19-810c-4f5b-bfc6-de432d97f4b8",
            "uniqueId": "1c8594a8-3837-4fb3-8c22-b630ff7d6896",
            "id": "PLAN_1",
            "orderToken": "83729d45-5c93-4251-856c-75ca52f8b5dc",
            "url": "https://snipcart.com",
            "creationDate": "2016-07-18T20:48:26.937Z",
            "modificationDate": "2016-07-18T20:48:26.937Z",
            "name": "Monthly subscription",
            "interval": "Month",
            "intervalCount": 1,
            "trialPeriodInDays": null,
            "firstPaymentDate": "2016-07-18T00:00:00Z",
            "amount": 20.00,
            "amountWithTaxes": 23.00,
            "totalAmountWithTaxes": 23.00,
            "quantity": 1,
            "totalAmount": 20.00,
            "metadata": {
                "test": "test"
            },
            "startsOn": "2016-07-18T00:00:00Z"
        },
        "user": {
            "id": "26886945-4b0b-4b06-a1f6-ff1e5125ad09",
            "email": "geeks@snipcart.com",
            "statistics": {
                "ordersCount": 0,
                "ordersAmount": null,
                "subscriptionsCount": 0
            },
            "creationDate": "2014-07-18T13:59:19.137Z",
            "mode": "Test",
            "shippingAddressSameAsBilling": false,
            "status": "Confirmed",
            "gravatarUrl": "https://www.gravatar.com/avatar/6f53dd6f5e6d9c6bdcbb1cdbc50554b7?s=70&d=https%3a%2f%2fcdn.snipcart.com%2fassets%2fimages%2favatar.jpg",
            "billingAddress": {
                "fullName": "Snipcart",
                "name": "Snipcart",
                "company": "Snipcart",
                "address1": "4885 1ere Avenue",
                "address2": null,
                "city": "Québec",
                "country": "CA",
                "postalCode": "G1H2T5",
                "province": "QC",
                "phone": null
            },
            "shippingAddress": {
                "fullName": "Snipcart",
                "name": "Snipcart",
                "company": "Snipcart",
                "address1": "4885 1ere Avenue",
                "address2": null,
                "city": "Québec",
                "country": "CA",
                "postalCode": "G1H2T5",
                "province": "QC",
                "phone": "418 888 8888"
            }
        },
        "id": "fef13e19-810c-4f5b-bfc6-de432d97f4b8",
        "creationDate": "2016-07-18T20:48:49.53Z",
        "modificationDate": "2016-07-18T20:48:49.53Z",
        "cancelledOn": null,
        "totalSpent": 23.00,
        "status": "Paid",
        "metadata": {
            "test": "test"
        }
    }
}

subscription.cancelled

{
    "eventName": "subscription.cancelled",
    "mode": "Live",
    "createdOn": "2016-07-19T15:57:45.0389264Z",
    "content": {
        "id": "7bd96e65-d5a9-447e-9f78-4719952c84e2",
        "creationDate": "2016-07-18T19:00:33.14Z",
        "modificationDate": "2016-07-18T19:00:33.14Z",
        "cancelledOn": "2016-07-19T15:57:40.7788419Z",
        "totalSpent": 0.0,
        "status": "Paid",
        "user": {
            "id": "26886945-4b0b-4b06-a1f6-ff1e5125ad09",
            "email": "charles@snipcart.com",
            "statistics": {
                "ordersCount": 0,
                "ordersAmount": null,
                "subscriptionsCount": 0
            },
            "creationDate": "2014-07-18T13:59:19.137Z",
            "mode": "Test",
            "shippingAddressSameAsBilling": false,
            "status": "Unconfirmed",
            "sessionToken": null,
            "gravatarUrl": "https://www.gravatar.com/avatar/6f53dd6f5e6d9c6bdcbb1cdbc50554b7?s=70&d=https%3a%2f%2fcdn.snipcart.com%2fassets%2fimages%2favatar.jpg",
            "billingAddress": {
                "fullName": "Snipcart",
                "firstName": null,
                "name": "Snipcart",
                "company": "Snipcart",
                "address1": "4885 1ere Avenue",
                "address2": null,
                "city": "Québec",
                "country": "CA",
                "postalCode": "G1H2T5",
                "province": "QC",
                "phone": null
            },
            "shippingAddress": {
                "fullName": "Snipcart",
                "name": "Snipcart",
                "company": "Snipcart",
                "address1": "4885 1ere Avenue",
                "address2": null,
                "city": "Québec",
                "country": "CA",
                "postalCode": "G1H2T5",
                "province": "QC",
                "phone": "418 888 8888"
            }
        },
        "plan": {
            "subscriptionId": null,
            "uniqueId": "35111b80-190a-429b-8a08-e5a9cb1d024c",
            "id": "PLAN_1",
            "orderToken": "8ecebf48-7b47-4317-885c-cf4cb35c4a06",
            "url": "https://snipcart.com",
            "creationDate": "2016-07-18T19:00:14.717Z",
            "modificationDate": "2016-07-18T19:00:14.717Z",
            "name": "Monthly subscription",
            "interval": "Month",
            "intervalCount": 1,
            "trialPeriodInDays": null,
            "firstPaymentDate": "2016-07-19T00:00:00Z",
            "amount": 20.0,
            "amountWithTaxes": 20.0,
            "totalAmountWithTaxes": 20.0,
            "quantity": 1,
            "totalAmount": 20.0,
            "metadata": {
                "ble": "ble",
                "ok": "Nooo shit"
            },
            "startsOn": "2016-07-19T00:00:00Z"
        }
    }
}

subscription.invoice.created

{
    "eventName": "subscription.invoice.created",
    "mode": "Live",
    "createdOn": "2016-07-18T20:48:53.9670522Z",
    "content": {
        "subscription": {
            "plan": {
                "subscriptionId": "fef13e19-810c-4f5b-bfc6-de432d97f4b8",
                "uniqueId": "1c8594a8-3837-4fb3-8c22-b630ff7d6896",
                "id": "PLAN_1",
                "orderToken": "83729d45-5c93-4251-856c-75ca52f8b5dc",
                "url": "https://snipcart.com",
                "creationDate": "2016-07-18T20:48:26.937Z",
                "modificationDate": "2016-07-18T20:48:26.937Z",
                "name": "Monthly subscription",
                "interval": "Month",
                "intervalCount": 1,
                "trialPeriodInDays": null,
                "firstPaymentDate": "2016-07-18T00:00:00Z",
                "amount": 20.00,
                "amountWithTaxes": 23.00,
                "totalAmountWithTaxes": 23.00,
                "quantity": 1,
                "totalAmount": 20.00,
                "startsOn": "2016-07-18T00:00:00Z"
            },
            "user": {
                "id": "26886945-4b0b-4b06-a1f6-ff1e5125ad09",
                "email": "charles@snipcart.com",
                "statistics": {
                    "ordersCount": 0,
                    "ordersAmount": null,
                    "subscriptionsCount": 0
                },
                "creationDate": "2014-07-18T13:59:19.137Z",
                "mode": "Test",
                "shippingAddressSameAsBilling": false,
                "status": "Unconfirmed",
                "sessionToken": null,
                "gravatarUrl": "https://www.gravatar.com/avatar/6f53dd6f5e6d9c6bdcbb1cdbc50554b7?s=70&d=https%3a%2f%2fcdn.snipcart.com%2fassets%2fimages%2favatar.jpg",
                "billingAddress": {
                    "fullName": "Snipcart",
                    "name": "Snipcart",
                    "company": "Snipcart",
                    "address1": "4885 1ere Avenue",
                    "address2": null,
                    "city": "Québec",
                    "country": "CA",
                    "postalCode": "G1H2T5",
                    "province": "QC",
                    "phone": null
                },
                "shippingAddress": {
                    "fullName": "Snipcart",
                    "name": "Snipcart",
                    "company": "Snipcart",
                    "address1": "4885 1ere Avenue",
                    "address2": null,
                    "city": "Québec",
                    "country": "CA",
                    "postalCode": "G1H2T5",
                    "province": "QC",
                    "phone": "418 888 8888"
                }
            },
            "id": "fef13e19-810c-4f5b-bfc6-de432d97f4b8",
            "creationDate": "2016-07-18T20:48:49.53Z",
            "modificationDate": "2016-07-18T20:48:49.53Z",
            "cancelledOn": null,
            "totalSpent": 23.00,
            "status": "Paid"
        },
        "taxes": [{
            "taxName": "TVQ",
            "amount": 2.00,
            "numberForInvoice": "",
            "taxRate": 0.0997500000,
            "id": "d959a02a-27fb-465e-8705-19aac58ce4c7",
            "creationDate": "2016-07-18T20:48:49.703Z",
            "modificationDate": "2016-07-18T20:48:49.703Z"
        }, {
            "taxName": "TPS",
            "amount": 1.00,
            "numberForInvoice": "",
            "taxRate": 0.0500000000,
            "id": "2e870938-de43-4509-a943-48dacddad3a7",
            "creationDate": "2016-07-18T20:48:49.703Z",
            "modificationDate": "2016-07-18T20:48:49.703Z"
        }],
        "id": "2cdd18c9-c0d0-4cfc-8a51-8af01910693d",
        "creationDate": "2016-07-18T20:48:49.627Z",
        "modificationDate": "2016-07-18T20:48:49.627Z",
        "subscriptionId": "fef13e19-810c-4f5b-bfc6-de432d97f4b8",
        "amount": 20.00,
        "paid": true,
        "number": "SNIP2827",
        "total": 23.00
    }
}

Consume the webhook request

You must handle a POST request to your Webhooks URL.

PHP (5.0+)

<?php

$json = file_get_contents('php://input');
$body = json_decode($json, true);

if (is_null($body) or !isset($body['eventName'])) {
    // When something goes wrong, return an invalid status code
    // such as 400 BadRequest.
    header('HTTP/1.1 400 Bad Request');
    return;
}

switch ($body['eventName']) {
    case 'order.completed':
        // This is an order:completed event
        // do what needs to be done here.
        break;
}

// Return a valid status code such as 200 OK.
header('HTTP/1.1 200 OK');

C# ASP.NET MVC

using System.IO;
using System.Net;
using System.Web.Mvc;
using Newtonsoft.Json;

namespace MyApplication.Controllers
{
    public class WebhooksController : Controller
    {
        [HttpPost]
        public ActionResult Receive()
        {
            Request.InputStream.Position = 0;
            Request.InputStream.Seek(0, SeekOrigin.Begin);
            using(var reader = new StreamReader(Request.InputStream))
            {
                var json = reader.ReadToEnd();
                var body = JsonConvert.DeserializeObject<dynamic>(json);
                try
                {
                    switch ((string)body.eventName)
                    {
                        case "order.completed":
                            // This is an order:completed event
                            // do what needs to be done here.
                            break;
                    }
                    // Return a valid status code such as 200 OK.
                    return new HttpStatusCodeResult(HttpStatusCode.OK);
                }
                catch
                {
                    // When something goes wrong, return an invalid status code
                    // such as 400 BadRequest.
                    return new HttpStatusCodeResult(HttpStatusCode.BadRequest);
                }
            }
        }
    }
}

Ruby (Rails)

class WebhookController < ApplicationController
    def event
        begin
            data = ActiveSupport::JSON.decode(request.body.read)
            case data[:eventName]
            when 'order.completed'
            # This is an order:completed event
            # do what needs to be done here.
            end
        rescue
            # When something goes wrong, return an invalid status code
            # such as 400 BadRequest.
            head :bad_request
        else
            # Return a valid status code such as 200 OK.
            head :ok
        end
    end
end