User guide: webhooks

User guide: webhooks

🔐 Introduction to Using Webhooks

Our platform allows you to configure webhooks to receive automatic updates on key events related to your orders and incidents. This allows you to keep your systems synchronized without the need for manual queries.

📌 What are Webhooks?

A webhook is an automatic call our system makes to a URL you configure whenever a relevant event occurs (such as a change in the status of an order or incident). This way, your system can react immediately to these changes.

🔑 Initial Setup

To start using webhooks:
  1. Go to the My Account > Access Token section.
  2. Create an API Key with permissions over your orders and issues.
  3. Configure two endpoints (public URLs):
  4. One to receive order status updates.
  5. Another to receive incident status updates.

✅ Security: HMAC signatures (optional for now)

To validate the authenticity of the events you receive, each webhook can include a digital signature in the header:
  1. Header : X-Dropea-Hmac-Sha256
  2. Content : A SHA256 hash generated using the POST body (payload) and your corresponding API Key as the secret key.
This allows you to verify that the request is actually coming from our system and has not been altered, similar to what Shopify does with its webhooks system .

⚠️ Important: Signature validation is currently optional, but its implementation is recommended to strengthen security.

🛍️ Order Status Update

When the status of an order is updated, the system sends a notification to the configured webhook with the following event structure:

❌ Example 1: Order goes from Confirmed to Cancelled (Payload to Receive)
  1. {"topic":"order:status_update","order_id":265494,"prev_status":"confirmed","new_status":"cancelled","updated_at":"2025-05-29 14:14:58"}

✅ Example 2: Order goes from Pending to Confirmed (Payload to Receive)
  1. {"topic":"order:status_update","order_id":265494,"prev_status":"pending","new_status":"confirmed","updated_at":"2025-05-29 14:14:58"}

🔁 Example 3: Order goes from Error to Pending (Payload to Receive)
  1. {"topic":"order:status_update",
  2. "order_id":265496,"prev_status":"error","new_status":"pending","updated_at":"2025-05-29 14:38:05"}

🛠️ Incidence Update

📌 Example: Incident goes from Pending to Customer Handled (Payload to Receive)
  1. {
  2. "topic": "incidence:status_update",
  3. "new_status": "client_managed",
  4. "updated_at": "2025-02-13 14:23:56",
  5. "prev_status": "pending",
  6. "incidence_id": 189044
  7. }

🔄 Example 2: Incident goes from Pending to Solution Sent
  1. {
  2. "topic": "incidence:status_update",
  3. "incidence_id": 265494,
  4. "prev_status": "client_managed",
  5. "new_status": "resolution_send",
  6. "updated_at": "2025-05-29 16:10:45"
  7. }

✅ Example 3: Incident goes from Solution Sent to Resolved (Payload to Receive)
  1. {
  2. "topic": "incidence:status_update",
  3. "incidence_id": 265494,
  4. "prev_status": "solution_send",
  5. "new_status": "resolved",
  6. "updated_at": "2025-05-29 17:42:30"
  7. }

📌 Details by field


Field
Guy Description
topic
string
It can be "order:status_update" or "incidence:status_update" , depending on the source of the event.
order_id
integer
ID of the affected order. Present only if topic is order:status_update.
incidence_id
integer
ID of the affected issue. Present only if topic is incidence:status_update.
prev_status
string
Previous state of the object. E.g., "pending," "confirmed," "error."
new_status
string
New state after change.
updated_at
date
Date and time of the change. This field is in the Europe/Madrid time zone , which is:
— UTC+2 in summer (daylight saving time)
— UTC+1 in winter (standard time)



    • Related Articles

    • User Guide: Dropea's GraphQL API with Apollo

      ? Generate API Key in dropea 1️⃣ Go to My Account → Access Tokens 2️⃣ Give your API Key a name ✏️ 3️⃣ Optionally, you can add an expiration date. ⏳ (If you don't define one, the API Key will be permanent.) 4️⃣ Select the permissions (scopes) that ...

    • Chatby Activation Guide

      Boost your sales, confirm orders, and resolve issues automatically with Chatby's AI. In the following guide we show you how to activate it ▶️ https://goo.su/nP0SY We also share a playlist with step-by-step video tutorials to get you started ▶️ Chatby ...

    • Where can I find a guide to get started setting up my Dropea account?

      Once you log in to your dropshipper account, you'll find a guide with the first steps in the Dashboard section of the panel, in the left-hand side menu (it's the first one that appears). Each step has its own instructions attached, and if you click ...

    • 5. Start selling

      Congratulations! If you've made it this far and all the previous steps have been completed successfully, your store is now ready for you to start selling . Important recommendation: To facilitate user conversions , it's essential to use Releasit or ...

    • Orders not displayed in dropea

      Active filters If you can't see your orders in Dropea, clear all the filters you've set in the orders section and they should appear. By default, Dropea will always show you orders from the last 7 days, but if you tap the date filter (or any other ...