GuidesAPI EndpointsChangelog
Log In
Guides

Callbacks

Suggest Edits

Callbacks, also referred to as webhooks, are secure HTTP requests made from Weedmaps to your configured system. These requests carry a payload that is the JSON-formatted Order object.

There are two callback events related to the WM Orders service: Draft and Create.
A specific callback URL can be configured for each of these events, or a single URL can be configured as a default for all events.

Merge Variables

Weedmaps callbacks support the use of merge variables in the configuration of the URL. To interpolate the values of these variables, use the format {{ variableName }} when configuring the URL string.

Below is an example URL with the merchantId variable as a query parameter.

https://integrator-host.com/callbacks/weedmaps/orders?merchant_id={{merchantId}}

Supported Merge Variables

As of October 2020, the merge variables listed below are supported by the Orders API.

  • merchantId — The unique identifier for each location of a client retailer, also referred to as the Weedmaps Menu ID. This identifier is the same ID used for the Menu API integration.

Authenticating Signatures

Callbacks from Weedmaps are signed with an HMAC SHA256 signature included as a header Signature on the callback request.

When establishing an integration with the Orders callbacks, integrators will be provided with a client secret that is unique to their integration. The client secret will be a version 4 UUID.

To confirm authenticity of the callback request:

  1. Using HMAC SHA256 encryption, encrypt the JSON body of the callback as the message and the provided client secret as the secret.
  2. Encode the encrypted string using Base64 encoding.
  3. Compare the encoded string against the value of the Signature header on the callback request.
  4. If these strings match, the callback is authentic.

Here's a Signature check example below:

const crypto = require('crypto');

/**
 * Generates HMAC-SHA256 signature and encodes in Base64.
 * EXAMPLE ONLY
 * 
 * @param {string} jsonBody - The raw JSON string.
 * @param {string} clientSecret - The shared secret key.
 * @returns {string} - Base64-encoded HMAC signature.
 */
function generateSignature(jsonBody, clientSecret) {
    return crypto.createHmac('sha256', clientSecret)
        .update(jsonBody)
        .digest('base64');
}

/**
 * Verifies HMAC-SHA256 signature using Base64 encoding and secure comparison.
 * 
 * @param {string} jsonBody - The raw JSON string.
 * @param {string} clientSecret - The shared secret key.
 * @param {string} receivedSignature - The Base64-encoded signature to verify.
 * @returns {boolean} - True if the signature is valid, false otherwise.
 */
function verifySignature(jsonBody, clientSecret, receivedSignature) {
    const expectedSignature = generateSignature(jsonBody, clientSecret);

    const expectedBuffer = Buffer.from(expectedSignature, 'base64');
    const receivedBuffer = Buffer.from(receivedSignature, 'base64');

    if (expectedBuffer.length !== receivedBuffer.length) {
        return false;
    }

    return crypto.timingSafeEqual(expectedBuffer, receivedBuffer);
}

// Example usage
const jsonBody = JSON.stringify({ order_id: 'abc123', status: 'accepted' });
const clientSecret = 'super-secret-key-1234';

// Simulate a signature that would be received from a webhook sender
const signatureToSend = generateSignature(jsonBody, clientSecret);

// Simulate receiving and verifying the signature
const isValid = verifySignature(jsonBody, clientSecret, signatureToSend);

console.log('Generated Signature:', signatureToSend);
console.log('Callback is authentic:', isValid);

Events

Draft

After a customer/patient has finished shopping and they are ready to check out, they are shown a preliminary order total with estimated taxes and fees. Before the order is sent to the retailer, Weedmaps sends the POS what's referred to as a Draft Order — or Draft event — to cross-check the accuracy of prices, applicable taxes and fees.

Below is a screenshot with an example of a Draft Order as it's displayed to a customer/patient in the Weedmaps UI.

The Draft event is asking for a quote. This gives the integrated POS platform the opportunity to more accurately represent the cost that the customer will incur.

The Draft event is a synchronous callback that expects a response confirming item availability and order totals estimation.

The order payload will be delivered in the request with a status of DRAFT "status":"DRAFT". This payload will also include line items, discounts, and any fees configured for Weedmaps orders. Limited or no customer information is provided during the Draft event.

Here is an example of a Draft event with a status of DRAFT.

{
  "fees": [
    {
      "name": "Weedmaps Service Fee",
      "amount": "0.00",
      "feeType": "WM_SERVICE_FEE"
    },
    {
      "name": "Delivery Fee",
      "amount": "0.00",
      "feeType": "DELIVERY_FEE"
    }
  ],
  "taxes": [
    {
      "name": "Excise tax",
      "amount": "0.24",
      "taxType": "EXCISE"
    },
    {
      "name": "Sales tax",
      "amount": "0.24",
      "taxType": "SALES"
    }
  ],
  "seller": {
    "id": "835493541",
    "name": "The Grow - North Side",
    "city": "Des Moines",
    "phone": "+13027451360",
    "address1": null,
    "address2": "",
    "province": "IA",
    "postalCode": "90277",
    "countryCode": "US"
  },
  "source": "WEEDMAPS",
  "status": "DRAFT",
  "orderId": "9779604",
  "version": "2020-05-08",
  "currency": "USD",
  "customer": {
    "id": "",
    "dob": null,
    "phone": "",
    "lastName": "",
    "firstName": "",
    "hasMedicalRecommendation": true,
    "medicalRecommendation": {
      "id": "123456789",
      "expires": "2025-01-01",
      "caregiverId": "12345",
      "province": "CA"
    }
  },
  "feeTotal": "0.00",
  "payments": [
    {
      "paymentType": "CREDIT",
      "amount": "99.99",
      "processor": "MERRCO",
      "transactionId": "abc123-456def",
      "success": true
    }
  ],
  "subtotal": "20.00",
  "taxTotal": "0.48",
  "createdAt": "2020-09-29T18:07:38Z",
  "discounts": [],
  "documents": [],
  "lineItems": [
    {
      "id": "21533747",
      "url": "https://weedmaps.com/deliveries/commerce-delivery-demo/product-grams-8g",
      "name": "Product Grams 8g",
      "brand": null,
      "imageUrl": "https://images.weedmaps.com/large/image_missing.jpg",
      "quantity": 1,
      "externalId": "5f6a5043d9b18c4826795b1a",
      "wmProductId": "45885942",
      "adjustedPrice": "20.00",
      "originalPrice": "20.00",
      "weightBreakpoint": "TWO_GRAM",
      "unitOfMeasure": {
        "unit": "GRAM",
        "value": "2"
      }
    }
  ],
  "grandTotal": "20.48",
  "customerNote": "",
  "discountTotal": "0.00",
  "lastModifiedAt": "2020-09-29T18:07:34Z",
  "shippingAddress": {
  	"address1": "4 Pacocha Groves",
   	"address2": "Apt. 307",
    "city": "Barrett",
    "countryCode": "US",
 	  "county": "Orange County",
    "latitude": "33.666633",
    "longitude": "-117.7584978",
    "postalCode": "10000",
    "province": "CA"
  },
  "deliveryPackages": [],
  "fulfillmentMethod": "DELIVERY",
  "requestedSchedulingInfo": null
}

Responding to this event with an order payload will update the corresponding order with estimates relayed in the response. These updates will be relayed to the customer/patient through the Weedmaps UI.

Below is a screenshot using the same example order. The taxes and fees have been updated, and the new totals are shown to the customer/patient.

If this request times out or errors, then the original cart estimates presented to the customer/patient will remain unchanged in the ordering process.

Create

The Create event is an asynchronous callback that expects a response with status code 200 or 201. If the request receives an error or times out, two more attempts are made.

The order payload included in this request will have a status of PENDING and will contain the complete order including the customer/patient information.

Below is an example of a Create event with a status of PENDING.

{
  "fees": [
    {
      "name": "Weedmaps Service Fee",
      "amount": "0.00",
      "feeType": "WM_SERVICE_FEE"
    },
    {
      "name": "Delivery Fee",
      "amount": "0.00",
      "feeType": "DELIVERY_FEE"
    }
  ],
  "taxes": [
    {
      "name": "Excise tax",
      "amount": "0.27",
      "taxType": "EXCISE"
    },
    {
      "name": "Sales tax",
      "amount": "1.50",
      "taxType": "SALES"
    }
  ],
  "seller": {
    "id": "835493541",
    "name": "The Grow - North Side",
    "city": "Des Moines",
    "phone": "+13027451360",
    "address1": null,
    "address2": "",
    "province": "IA",
    "postalCode": "90277",
    "countryCode": "US"
  },
  "source": "WEEDMAPS",
  "status": "PENDING",
  "orderId": "9763822",
  "version": "2020-05-08",
  "currency": "USD",
  "customer": {
    "id": "9063167",
    "dob": "1976-03-03",
    "phone": "9997770082",
    "lastName": "Dobbs",
    "firstName": "Bob",
    "hasMedicalRecommendation": true,
    "medicalRecommendation": {
      "id": "123456789",
      "expires": "2025-01-01",
      "caregiverId": "12345",
      "province": "CA"
    }
  },
  "feeTotal": "0.00",
  "payments": [
    {
      "paymentType": "CREDIT",
      "amount": "99.99",
      "processor": "MERRCO",
      "transactionId": "abc123-456def",
      "success": true
    }
  ],
  "subtotal": "10.00",
  "taxTotal": "1.77",
  "createdAt": "2020-09-28T22:24:44Z",
  "discounts": [],
  "documents": [
    {
      "url": "https://api-g.weedmaps.com/oos/merchants/835493541/documents/9763822--dde72278-facc-41ff-9548-d4e9b149edbd/url",
      "documentType": "MEDICAL_RECOMMENDATION"
    },
    {
      "url": "https://api-g.weedmaps.com/oos/merchants/835493541/documents/9763822--cba1ca4a-a1bc-43fc-94ad-4a1407a75a08/url",
      "documentType": "GOVERNMENT_ISSUED_ID"
    }
  ],
  "lineItems": [
    {
      "id": "21498418",
      "url": "https://weedmaps.com/deliveries/commerce-delivery-demo/product-grams-8g-custom",
      "name": "Product Grams 8g, CUSTOM",
      "brand": null,
      "imageUrl": "https://images.weedmaps.com/large/image_missing.jpg",
      "quantity": 1,
      "externalId": "5f6a5043d9b18c4826795b1a",
      "wmProductId": "46148193",
      "adjustedPrice": "10.00",
      "originalPrice": "10.00",
      "weightBreakpoint": "UNIT",
      "unitOfMeasure": {
        "unit": "UNIT",
        "value": "1"
      }
    }
  ],
  "grandTotal": "11.77",
  "customerNote": "",
  "discountTotal": "0.00",
  "lastModifiedAt": "2020-09-28T22:24:44Z",
  "shippingAddress": {
    "city": "Johnston",
    "address1": "6523 Northwest 97th Street",
    "address2": null,
    "latitude": "41.677185",
    "province": "IA",
    "county": "Polk",
    "longitude": "-93.751022",
    "postalCode": "50131",
    "countryCode": "US"
  },
  "deliveryPackages": [],
  "fulfillmentMethod": "DELIVERY",
  "requestedSchedulingInfo": {
        "windowStartAt": "2020-09-29T12:00:00Z",
        "windowEndAt": "2020-09-29T13:00:00Z"
    }
}

Updated about 1 month ago