> For the complete documentation index, see [llms.txt](https://chord-commerce.gitbook.io/oms-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chord-commerce.gitbook.io/oms-guide/how-to-receive-event-notifications-with-webhooks.md). # How to: Receive event notifications with webhooks Chord OMS uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when an order is completed, canceled, or when a shipment changes status. Begin using webhooks with your Chord OMS integration in just two steps: 1. Create a webhook endpoint on your server. 2. Register the endpoint on the Chord OMS Dashboard to go live. ### What are webhooks Webhooks refer to a combination of elements that collectively create a notification and reaction system within a larger integration. *Metaphorically*, webhooks are like a phone number that Chord OMS calls to notify you of activity in your Chord OMS. The webhook endpoint is the person answering that call who takes actions based upon the specific information it receives. *Non-metaphorically*, the webhook endpoint is just more code on your server. The webhook endpoint has an associated URL (e.g. ****). The Chord OMS notifications are Webhook Event objects. This Webhook Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. ### Build a webhook endpoint Write the code that properly handles webhook notifications. The first step to adding webhooks to your Chord OMS integration is to build your own custom endpoint. Creating a webhook endpoint on your server is no different from creating any page on your website. ### Key considerations For each event occurrence, the Chord OMS POSTs the webhook data to your endpoint in JSON format. The full event details are included and can be used directly after parsing the JSON into an Event object. The webhook endpoint needs to expect data through a POST request and confirm successful receipt of that data. To acknowledge receipt of an event, your endpoint must return an allowed HTTP status code to the Chord OMS. All response codes outside these, including **3xx** codes, indicate to the Chord OMS that you did not receive the event. {% hint style="info" %} If the Chord OMS does not receive a valid HTTP status code, the notification attempt is repeated up to 5 times. {% endhint %} Because properly acknowledging receipt of the webhook notification is so important, your endpoint should return an allowed HTTP status code prior to any complex logic that could cause a timeout. #### Allowed HTTP status code * 200 * 201 * 202 * 204 ### Event types This is a list of all the types of events we currently send.
Event NamePayload ObjectDescription
order_completedOrderOccurs whenever an order is completed
order_cancelledOrderOccurs whenever an order is cancelled
shipment_shippedShipmentOccurs whenever a shipment is shipped
shipment_updatedShipmentOccurs whenever a shipment receives an update (like a status change different from shipped or a tracking details update)
shipment_delivery_status_updatedShipmentOccurs whenever the tracking code related to the shipment receives a delivery status update
stock_item_back_in_stockStock ItemOccurs whenever a product variant is back in stock
stock_item_out_of_stockStock ItemOccurs whenever a product variant goes out of stock
{% hint style="warning" %} [shipping\_delivery\_status\_updated](#event-types) can only be used if you have a Fulfillment Integration with EasyPost. {% endhint %} {% hint style="info" %} Your webhook endpoints should be configured to receive only the types of events required by your integration. Listening for extra events (or all events) will put undue strain on your server and is not recommended. {% endhint %} #### Examples of event payloads {% tabs %} {% tab title="Order" %} ``` { "event_name": "order_*", "order": { "id": 1, "number": "ACS-176461162", "item_total": "10.0", "total": "10.63", "state": "complete", "adjustment_total": "0.63", "completed_at": "2021-10-05T10:44:38.312-04:00", "payment_total": "10.63", "shipment_state": "ready", "payment_state": "paid", "email": "example@mail.com", "created_at": "2021-10-05T10:43:15.371-04:00", "updated_at": "2021-10-05T10:44:39.749-04:00", "currency": "USD", "last_ip_address": null, "shipment_total": "0.0", "additional_tax_total": "0.63", "promo_total": "0.0", "channel": "chord", "included_tax_total": "0.0", "item_count": 1, "confirmation_delivered": true, "canceled_at": null, "canceler_id": null, "store_id": 2, "checkout_session_id": "cs_live_xxxxxxxxx", "commission_total": "0.0", "stripe_automatic_taxes": false, "subscription_order": false, "subscription_id": null, "cart_url": null, "user": { "id": 2, "email": "example@mail.com", "stripe_user_id": null }, "line_items": [ { "id": 4, "name": "Product 3", "sku": "product-3", "quantity": 1, "total": "$10.00", "adjustments": [ { "id": 5, "amount": "$0.63", "label": "NY 6.250%", "source_type": "Tax Rate", "promotion_code": null, "created_at": "2021-10-05T10:44:10.000-04:00", "updated_at": "2021-10-05T10:44:38.025-04:00" } ] } ], "shipments": [ { "id": 4, "tracking": null, "number": "H44458074123", "cost": "0.0", "shipped_at": null, "state": "ready", "created_at": "2021-10-05T10:44:09.939-04:00", "updated_at": "2021-10-05T10:44:40.123-04:00", "adjustment_total": "0.0", "additional_tax_total": "0.0", "promo_total": "0.0", "included_tax_total": "0.0", "pushed": false, "delivered_at": null, "delivery_status": null, "external_tracking_url": null, "label_url": null, "adjustments": [ { "id": 6, "amount": "$0.00", "label": "NY 6.250%", "source_type": "Tax Rate", "promotion_code": null, "created_at": "2021-10-05T10:44:10.005-04:00", "updated_at": "2021-10-05T10:44:38.042-04:00" } ] } ], "ship_address": { "id": 1, "firstname": "John", "lastname": "Doe", "address1": "10 Lovely Street", "address2": null, "city": "Herndon", "zipcode": "10001", "phone": null, "state": "New York", "country": "United States", "state_name": null, "alternative_phone": null, "company": null }, "bill_address": { "id": 1, "firstname": "John", "lastname": "Doe", "address1": "10 Lovely Street", "address2": null, "city": "Herndon", "zipcode": "10001", "phone": null, "state": "New York", "country": "United States", "state_name": null, "alternative_phone": null, "company": null }, "payments": [ { "id":4, "amount": "$0.00", "payment_method": "Stripe", "state": "invalid", "created_at": "2021-10-05T10:44:10.036-04:00", "updated_at": "2021-10-05T10:44:37.544-04:00" }, { "id":5, "amount": "$10.63", "payment_method": "Stripe", "state": "completed", "created_at": "2021-10-05T10:44:37.515-04:00", "updated_at": "2021-10-05T10:44:39.729-04:00" } ], "adjustments": [ ] } } ``` {% endtab %} {% tab title="Shipment" %} ``` { "event_name": "shipment_*", "shipment": { "id": 2, "tracking": null, "number": "H47476412682", "cost": "22.0", "shipped_at": "2021-10-20T13:11:26.126-04:00", "state": "shipped", "created_at": "2021-10-20T13:09:00.180-04:00", "updated_at": "2021-10-20T13:11:26.118-04:00", "adjustment_total": "1.38", "additional_tax_total": "1.38", "promo_total": "0.0", "included_tax_total": "0.0", "pushed": false, "delivered_at": "2021-10-28T10:14:16.146-04:00", "delivery_status": "delivered", "status_detail": "arrived_at_destination", "tracking_detail": "Delivered", "external_tracking_url": null, "label_url": null, "adjustments": [ { "id": 2, "amount": "$1.38", "label": "NY 6.250%", "source_type": "Tax Rate", "promotion_code": null, "created_at": "2021-10-20T13:09:39.377-04:00", "updated_at": "2021-10-20T13:10:52.404-04:00" } ] } } ``` {% endtab %} {% tab title="Stock Item" %} ``` { "event_name": "stock_item_*", "stock_item": { "id": 32, "stock_location": "default", "count_on_hand": 1000, "backorderable": true, "created_at": "2021-10-20T08:31:13.409-04:00", "updated_at": "2021-10-20T08:31:13.409-04:00", "variant": { "id": 32, "sku": "product-1-large-blue|product-2-small-blue|product-3", "is_master": false, "amount": "$20.00", "subscribable": true, "bundle": true, "url": "https://example.url.dev/bundles/kit-1", "main_image": "https://12345.cloudfront.net/store/images/attachments/000/000/001/small/test.jpg?123456", "updated_at": "2021-10-20T12:27:48.963-04:00", "created_at": "2021-10-20T08:31:13.397-04:00" } } } ``` {% endtab %} {% endtabs %} ### Complete your webhooks integration After building, and deploying your webhook, set up the endpoint so the Chord OMS knows where to send the events. #### Add endpoints from the Dashboard ![](/files/R4ZcdylO85Braug1hxp6) ![](/files/HDGEAlrbAKjbKDqCALkr) ![](/files/XMGLLSyy64FiW1xq7wYh) #### Add endpoints with the API ``` curl http://localhost:3000/api/webhook/endpoints \ -H 'Accept: */*' \ -H "Authorization: Bearer 1dad20831dc47cb20f8a3a8dc73a0ae41d83b32efadae4c2" \ -H 'Content-Type: application/json' \ -d '{ "endpoint": { "target_url": "https://example.com/my/webhook/endpoint", "events": ["order_completed", "order_cancelled"] } }' ``` ### Manage webhook endpoints Existing webhook endpoints can be updated or deleted in the Dashboard’s Webhooks settings section. #### View events When viewing information about a specific endpoint through the Dashboard, you can check all the attempts related to an endpoint by clicking on that endpoint edit icon in the Webhooks section: ![](/files/rBBB1ZSQ6AKpAQLCgySb) This shows the latest response from your endpoint, a list of all attempted webhooks, and the respective HTTP status codes the Chord OMS received: ![](/files/i0zrEyvBSWhQndNMlvP9) ![](/files/ncUx90WdTs2ZMfryQ7RJ) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://chord-commerce.gitbook.io/oms-guide/how-to-receive-event-notifications-with-webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.