Skip to main content

Working with TRAEDE webhooks

TRAEDE sends webhooks to an external return portal when a return transitions between statuses that require the portal to take action.

Setting up endpoints + secrets​

Inside TRAEDE the brand administrator configures the webhook_endpoint where webhooks should be delivered and retrieves the webhook_secret that TRAEDE generated for the portal. See Installing the Return Portal in TRAEDE.

Validating webhooks​

Every webhook includes a signature in the X-Traede-Signature-256 header. The signature is the hex-encoded HMAC-SHA256 of the raw JSON request body, using the portal's webhook_secret as the key.

Your portal should compute the same hash on the received body and compare it in constant time to the header value. Reject the request if they do not match.

<?php

$expected = hash_hmac('sha256', $rawBody, $webhookSecret);

if (!hash_equals($expected, $request->header('X-Traede-Signature-256'))) {
    abort(401, 'Invalid signature');
}

Delivery and retries​

Webhooks are delivered through TRAEDE's document exchange system, which retries transient failures with backoff. A webhook is considered delivered when your endpoint returns a 2xx response. Non-2xx responses are retried.

Supported webhooks​

return_received​

Sent once a return has transitioned to received inside TRAEDE and the resulting credit note has been created.

Payload shape:

{
  "webhook_type": "return_received",
  "data": {
    "return_id": 123,
    "rma": "RMA-1001",
    "order_number": "1001"
  }
}
ParameterData typeDescription
webhook_typestringAlways return_received for this webhook.
data.return_idintThe TRAEDE ID of the return. Use this as the {returnId} path parameter on finalize.
data.rmastringThe external RMA string that was supplied by the portal when the return was created.
data.order_numberstringThe order number of the order the return was created against.

On receipt, the portal is expected to issue the refund and call Finalize a return once the refund amount is known.