Skip to content

Webhooks

Webhooks provide real-time updates about events that occur on the ThredUp platform, such as changes in order status or item purchases. These updates, delivered in the form of notifications, contain identical data to that which is accessible through the API.

Configuration

To receive webhook notifications, you need to configure your webhook endpoints in the ThredUp platform. Each webhook configuration includes: - Webhook URL - Notification types to subscribe to

The ThredUp development team currently handles webhook configuration, as it is not yet available through the API.

Notification types

Event Description
ITEM_PURCHASED Notification is sent upon completing the purchase and finalizing payment. This allows you to reserve the item on other platforms where it may be listed.
ORDER_CREATED Notification is sent after the order has passed fraud verification and is ready for fulfillment.
ORDER_CANCELED A notification is sent when ThredUp customer support cancels a customer's order.
ORDER_REFUNDED Notification is sent when ThredUp customer support issues a refund, including partial refunds, to the customer.
ORDER_ADDRESS_UPDATED Notification is sent when the customer updates their shipping address.

Notification delivery

The system will try to deliver a notification 3 times. The system uses an exponential backoff of 5 minutes between delivery attempts.

If delivery fails after 3 attempts, the notification status will change to ERRORED and can only be delivered manually by the ThredUp development team.

Note

There is no guarantee of order for notification delivery: if a notification fails, other notifications associated with the same order may be delivered before the initial notification is retried.

Note

HTTP POST requests with application/json content type are used to send notifications.

Security

Webhook endpoints are required to use HTTPS. A signature header, generated using your ThredUp API key, is included in all webhook payloads to verify the payload's validity and ensure it has not been tampered with.

X-Thredup-Signature: abc123...

Note

If your system requires additional headers, such as an API key, we can include them in the notification payload.

Recommendations

  • Ensure your webhook endpoint can handle multiple requests at the same time.
  • Respond to webhooks quickly within 30 seconds to prevent timeouts.
  • Implement idempotency in your webhook handler to handle duplicate notifications.
  • Return appropriate HTTP status codes:
    • 2xx: Success
    • 4xx: Client error (will be retried)
    • 5xx: Server error (will be retried)