Webhooks

Webhook actions send orders to another system the moment a workflow runs. Use them when the other system can receive requests: Miva pushes each order instead of the other system pulling from a queue.

GET and POST#

For GET, Miva adds ?Order_ID=1001 to the URL, or &Order_ID=1001 if the URL already has a query string.

The POST payload#

The body is the order object on its own, with no wrapper. It has every order field plus the on-demand data that OrderList_Load_Query can return:

ship_method, cust_login, cust_pw_email, business_title, payment_module, customer, items, charges, coupons, discounts, payments, payment_data, notes, shipments, returns, shipping_details and CustomField_Values for every module, including each queue flag and the auditlog field.

The payload can’t be filtered or reshaped. If a workflow changes the order before the webhook action (for example, a queue action), the payload reflects the change. A shortened example:

{
    "id": 1001,
    "orderdate": 1588976246,
    "status": 0,
    "ship_fname": "Test",
    "ship_lname": "Order",
    "ship_email": "[email protected]",
    "ship_city": "San Diego",
    "ship_state": "CA",
    "ship_cntry": "US",
    "ship_method": "Free Shipping",
    "source": "shopper",
    "total": 10.00,
    "formatted_total": "$10.00",
    "items": [
        {
            "order_id": 1001,
            "line_id": 2,
            "status": 0,
            "code": "sample",
            "name": "Sample",
            "price": 10.00,
            "quantity": 1,
            "total": 10.00
        }
    ],
    "charges": [],
    "coupons": [],
    "discounts": [],
    "payments": [
        {
            "id": 3,
            "order_id": 1001,
            "type": 1,
            "amount": 10.00,
            "description": "Check"
        }
    ],
    "notes": [
        {
            "id": 1,
            "order_id": 1001,
            "notetext": "Automated Workflow: Order moved to queue \"New & Updated Orders\".",
            "dtstamp": 1588976246
        }
    ],
    "shipments": [],
    "returns": [],
    "CustomField_Values": {
        "customfields": {
            "order_instructions": ""
        },
        "orderworkflow": {
            "new_and_updated": "1",
            "successfully_retrieved_orders": ""
        }
    }
}

Authentication#

To call an endpoint behind HTTP basic authentication, attach credentials to the webhook action:

1. Add the credentials on the Order Workflow Authentication Credentials tab, or from the webhook action itself. Each set has a description, the type Basic, a username and an optional password.
2. Select them on each webhook action that needs them. One set can be shared by many webhooks.

Miva stores the username and password encrypted and sends Authorization: Basic <base64 username:password> with each request. The admin and the API show the username but never the password. Credentials that a workflow uses can’t be deleted until no webhook uses them.

Basic is the only authentication type. Webhooks don’t add a signature or custom headers, so to confirm a request came from your store, use credentials and HTTPS, or treat the request as a notice and fetch the order with the JSON API.

Delivery#

Each webhook is a single request:

• No retries. If the request fails (Miva can’t connect, or the connection times out), the action fails, the rest of that workflow’s actions are skipped, and the webhook isn’t sent again.
• Response not checked. Miva doesn’t look at the HTTP status or body. A 500 from your endpoint counts as delivered.
• No timeout setting. The server’s default applies.
• Failures aren’t reported when the workflow runs from a trigger. When it runs from the Wait Until True re-check, the failure is written to the scheduled task log.
• Duplicates happen. Workflows run on every trigger, so the same order can arrive more than once. Make your endpoint safe to call twice with the same order.

Because nothing is retried, don’t rely on a webhook alone for orders you can’t afford to miss. Pair it with a queue: have the workflow add the order to a queue, and let the other system pull from the queue as a backstop.

Receiving webhooks#

• Respond quickly. Miva waits for your response before running the workflow’s next action.
• Use the order id to match repeat deliveries.
• For orders created in the admin, add a condition such as length(order:payments) GT 0 with Wait Until True, so the webhook waits until the order is complete.