Introduction
API

SFTP
On this page

How do I know my integration is live & running?
There’s an Error or a Problem: How Can I Debug My Integration?
How can you debug the integration from the Sandbox environment and identify the scope of the error?
How do I verify the HMAC signature of a webhook request?

Troubleshooting#

Click below to jump to the topics:

How do I know my integration is live & running?#

You can monitor the integrations from Partner Portal directly. When OT API triggers orders to your webhook, success or failure is logged in the Shop Integrations > Order status updates tab. In the event of an observed error, it should be resolved by the Partner.

There’s an Error or a Problem: How Can I Debug My Integration?#

If you’re experiencing issues with your integration, follow these steps to identify and resolve the problem:

  • Check the Shops Integrations Plugin in the Partner Portal to verify that your integration is correctly set up and there are no errors demonstrated visibly

  • Gather key details about the issue, including error messages, timestamps, and any relevant API request/response logs.

  • Assess the impact – is the issue affecting all orders/promotions/catalog updates or just specific ones? How critical is the problem for your operations?

  • Contact your account manager and provide:

    • A clear description of the issue.

    • Error details (logs, screenshots, API responses).

    • The scale and impact on your business.

  • Retry or test the integration to see if the issue persists after making adjustments.

Providing complete and accurate information will help speed up the troubleshooting process.

How can you debug the integration from the Sandbox environment and identify the scope of the error?#

  • Place an order from the test store or use the sandbox environment in Partner Portal

  • Partner API/Orders should trigger the order to your configured webhook

  • The order can be tracked from the Partner Portal -> Shop Integrations plugin

  • A successful POST request to your webhook will have a 200 response

  • If the response is 4xx or 5xx– scope of error is with Partners, logged errors in the Order status updates tab must be reviewed and appropriate actions should be taken by Partner to adjust the webhook service. Partner’s internal service logs can also be utilised for effective debugging.

How do I verify the HMAC signature of a webhook request?#

This applies if your webhook uses HMAC signature authentication (see How to configure webhook and secret). For every request:

  1. Require exactly one X-DH-Signature header whose value is exactly 64 lowercase hexadecimal characters. Reject missing, duplicate or malformed signature headers.

  2. Capture the exact, uncompressed request body bytes before JSON parsing or any other transformation. If HTTP Content-Encoding is used, decompress the body before verification.

  3. Use the UTF-8 bytes of your signing secret as the HMAC key. Compute the HMAC-SHA256 digest over the body bytes and write it as lowercase hexadecimal.

  4. Compare the expected and received signatures with a constant-time comparison. Reject the request if they do not match.

  5. Process deliveries idempotently, using the event or order identifier when available. The signature covers the body only. It has no signed timestamp or replay window, and it does not prevent duplicate delivery.

Python example

import hashlib
import hmac
def is_valid(secret: str, raw_body: bytes, header_value: str) -> bool:
expected = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header_value)

Test vector

Use this to check your implementation. It is for tests only, so never use this secret in a real environment.

InputValue
Test-only signing secretMDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY
Exact request body (UTF-8){"order_id":"123","status":"READY"}
HMAC-SHA256, lowercase hex304ffd0a5dc5027c601585f417ce8722c5b6d0bc4ecd071e5cc6191128fb76d3
Complete headerX-DH-Signature: 304ffd0a5dc5027c601585f417ce8722c5b6d0bc4ecd071e5cc6191128fb76d3

Common signature problems

SymptomLikely cause
Signature never matchesThe body was parsed or re-serialized before hashing, or the wrong secret is in use
Matches in tests, fails in productionA proxy or framework changes the body, or a trailing newline is added or removed
Matches only for some requestsA compressed body was verified before decompression
Everything fails after a rotationThe verifier still uses the old secret
Lost the secretIt cannot be retrieved. Rotate it in Webhook Settings to get a new one

API≪ Use Cases - Endpoints ExplainedAPIFAQ ≫