Webhooks

Learn about using InStore webhooks to notify you of results from InStore.

Webhooks provide the means for InStore to notify you with the results of any process or notification generated by InStore. The InStore webhook sends a POST request to a URL that you preregister in the InStore Center, with the results of the process executed in your in-store application.

Set up a webhook

To set up a webhook, follow these steps:

  1. Set up an endpoint on your server to receive the webhook data. You'll need to create a script or program that listens for incoming requests at a specific URL. This can be done using a variety of programming languages and frameworks, depending on your server setup. InStore will send an HTTP POST to the URL you specify.

  2. Set up your endpoint to receive data in JSON format. This means that your script or program will receive data in the format of a JSON object, with properties and values that match the data being sent.

  3. Configure your endpoint to verify the SHA256 hashed signature that is sent with each webhook. This signature is a security measure that ensures that the data being sent to your endpoint is actually coming from InStore and has not been tampered with in transit.

  4. To verify the signature, you'll need to perform the following steps:

    1. Extract the signature from the incoming webhook request headers. The header key for the signature is typically named verification-signature.
    2. Use your own private key and the incoming request body to generate a SHA256 hash.
    3. Compare the generated hash to the signature included in the incoming request headers. If they match, then the data has not been tampered with and can be safely processed by your endpoint.
    4. Once you've verified the signature, you can process the incoming data as needed. This may involve storing it in a database, triggering other actions in your system, or sending a response back to our software to acknowledge receipt of the webhook.

    The specific details of setting up a webhook and verifying the signature may vary depending on the programming language, framework, and server setup you are using. You may need to consult your server documentation or contact a specialist to assist with the setup if you're not familiar with these concepts.

Webhook payload for payments

The webhook payload is a JSON object that contains the following properties:

FieldTypeDescription
cartIdStringUnique identifier for the Cart associated with the payment.
actionStringType of action being performed—in this case, it is set to payment.
tenderLineItemsArrayArray of objects that represent the tender line items for the payment.

tenderLineItems properties

Each object in the tenderLineItems array represents a payment tender line item and contains the following properties:

FieldTypeDescription
tender_typeStringType of payment tender used—in this case, it is set to Credit.
amountObjectContains information about the payment amount, including the value, currency, and precision.
charge_cardObjectContains information about the payment card used, including the processor, processor ID, last 4 digits of the card number, brand, account type, authorization response code, and other optional fields.
gift_cardObjectContains information about the gift card (or return voucher) used, including the issuer, number, last4, cvc, and type.
digital_walletObjectContains information about the digital wallet used.
mist_idStringOptional identifier that cross references payment transactions on the order with payments recorded in InStore.

Example payloads

Payment

Example webhook payload for a paymentjson
{
"cart_id": "001010499452",
"cartOrigin": "commercetools",
"action": "payment",
"tenderLineItems": [
{
"tender_type": "GiftCard",
"amount": {
"amount": 9778,
"currency": "USD",
"precision": 2
},
"reference": "001010499452",
"mist_id": "655b9179328a0ca4ac34b705",
"gift_card": {
"issuer": "NebulaTerra",
"number": "424838134735",
"last4": "4735",
"cvc": "",
"type": "ReturnCard"
}
}
]
}

Refund

Example webhook payload for a refundjson
{
"action": "refund",
"cartId": "001010501275",
"country": "US",
"returnCarts": [
{
"cartOrigin": "commercetools",
"orderNumber": "001010150829",
"refundLineItems": [
{
"_id": "655bc013328a0ca4ac34b8a2",
"tender_type": "Credit",
"amount": {
"amount": 4240,
"currency": "USD",
"precision": 2
},
"reference": "001010501275",
"charge_card": {
"processor_id": "pi_3OD88AC24rtrkoWS1yMbPozG",
"last4": "4242",
"brand": "visa",
"account_type": "credit",
"application_preferred_name": "",
"dedicated_file_name": "",
"authorizion_response_code": "3030",
"application_cryptogram": "",
"terminal_verification_results": ""
}
}
]
}
]
}

Bank deposit

Example webhook payload for a bank depositjson
{
"session_id": "6590671323e1e757628aab25",
"location": "001",
"workstation": "01",
"user_id": "ABC",
"action": "bankdeposit",
"cashdrawer": "00",
"last_count_id": "64cbd5f05ad61ab36409538d",
"amount": {
"amount": 100,
"currency": "USD",
"precision": 2
},
"reason": {
"code": "01",
"label": "test"
}
}

Cash count

Example webhook payload for a cash countjson
{
"session_id": "6590671323e1e757628aab25",
"location": "001",
"cashdrawer": "00",
"user_id": "ABC",
"last_count_id": "64cbd5f05ad61ab36409538d",
"amount": {
"amount": 100,
"currency": "USD",
"precision": 2
},
"expected": {
"amount": -100,
"currency": "undefined",
"precision": "undefined"
},
"delta": {
"amount": 200,
"currency": "USD",
"precision": 2
},
"reason": {
"code": "01",
"label": "test"
},
"action": "cashcount"
}

Cash in

Example webhook payload for cashing injson
{
"session_id": "6761b10ebbc2e824b72acb5a",
"location": "001",
"workstation": "03",
"user_id": "ABC",
"action": "cashin",
"cashdrawer": "03",
"last_count_id": "67567a46107a4a5888fe4eb8",
"amount": {
"amount": 2000,
"currency": "USD",
"precision": 2
},
"reason": {
"code": "02",
"label": "test"
}
}

Cash out

Example webhook payload for cashing outjson
{
"session_id": "6590671323e1e757628aab25",
"location": "001",
"workstation": "01",
"user_id": "ABC",
"action": "cashout",
"cashdrawer": "00",
"last_count_id": "64cbd5f05ad61ab36409538d",
"amount": {
"amount": 100,
"currency": "USD",
"precision": 2
},
"reason": {
"code": "01",
"label": "test"
}
}

Safe deposit or safe transfer

Example webhook payload for a safe deposit or transferjson
{
"session_id": "6590671323e1e757628aab25",
"location": "001",
"workstation": "01",
"user_id": "ABC",
"action": "transferin",
"cashdrawer": "64cbd5fe5ad61ab3640954b1",
"last_count_id": "64cbd5f05ad61ab36409538d",
"amount": {
"amount": 100,
"currency": "USD",
"precision": 2
},
"reason": {
"code": "01",
"label": "test"
}
}

Transfer in

Example webhook payload for transferring injson
{
"session_id": "6590671323e1e757628aab25",
"location": "001",
"workstation": "01",
"user_id": "ABC",
"action": "transferin",
"cashdrawer": "00",
"last_count_id": "64cbd5f05ad61ab36409538d",
"amount": {
"amount": 100,
"currency": "USD",
"precision": 2
},
"reason": {
"code": "01",
"label": "test"
}
}

Transfer out

Example webhook payload for transferring outjson
{
"session_id": "6590671323e1e757628aab25",
"location": "001",
"workstation": "01",
"user_id": "ABC",
"action": "transferout",
"cashdrawer": "64cbd5f05ad61ab36409538f",
"last_count_id": "64cbd5f05ad61ab36409538d",
"amount": {
"amount": 100,
"currency": "USD",
"precision": 2
},
"reason": {
"code": "01",
"label": "test"
}
}