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:
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.
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.
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.
To verify the signature, you'll need to perform the following steps:
- Extract the signature from the incoming webhook request headers. The header key for the signature is typically named
verification-signature
. - Use your own private key and the incoming request body to generate a SHA256 hash.
- 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.
- 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.
- Extract the signature from the incoming webhook request headers. The header key for the signature is typically named
Webhook payload for payments
The webhook payload is a JSON object that contains the following properties:
Field | Type | Description |
---|---|---|
cartId | String | Unique identifier for the Cart associated with the payment. |
action | String | Type of action being performed—in this case, it is set to payment . |
tenderLineItems | Array | Array 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:
Field | Type | Description |
---|---|---|
tender_type | String | Type of payment tender used—in this case, it is set to Credit . |
amount | Object | Contains information about the payment amount, including the value, currency, and precision. |
charge_card | Object | Contains 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_card | Object | Contains information about the gift card (or return voucher) used, including the issuer , number , last4 , cvc , and type . |
digital_wallet | Object | Contains information about the digital wallet used. |
mist_id | String | Optional identifier that cross references payment transactions on the order with payments recorded in InStore. |
Example payloads
Payment
{"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
{"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
{"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
{"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
{"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
{"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
{"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
{"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
{"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"}}