Introduction

Webhooks in ReturnBear are centered around events. By registering a webhook subscription, your application can receive real-time POST requests when certain events occur. This enables your applications to react immediately to actions within our system.

Getting Started

Configuration

Start by registering a webhook using the /api/webhooks API. You should register an HTTPS url and select an event you are interested in. When you create the webhook, you will receive a secret key in the response body. You can use this key to validate the signature of the webhook request body.

Please reach out to ReturnBear support ([email protected]) or on the shared ReturnBear Slack channel if you need to register a webhook. We will be able to do this manually for you. The information you need to provide is the URL of the endpoint you want to receive webhooks at and the event(s) you are interested in. Once we have registered the webhook(s) for you, we will send you a secret key to validate the signature of the webhook request body.

Security

Each webhook payload is signed using an HMAC signature to ensure the data integrity and authenticity of the request. This signature is included in the returnbear-signature header of the request.

When you register a webhook, you will receive a secret key. You can use this key to build an HMAC signature of the incoming request body and compare it to the returnbear-signature request header.

Webhook delivery behaviour

Here are some important considerations regarding our event system:

A single operation can emit multiple events.
The order of events within a given operation (ie: return case approval) is not guaranteed, don't rely on it.
Delivery of webhooks is not guaranteed. You can retrieve a list of webhooks sent to your endpoint via the /api/webhooks/{id}/events API.

Retries

ReturnBear will attempt to deliver webhooks for up to 3 days using an exponential backoff. You can query the webhook events API for your endpoint to see events that are pending delivery.

Disabling an endpoint due to failure

ReturnBear will attempt to notify you of a misconfigured endpoint by email if the endpoint hasn’t responded with a 2xx HTTP status code for multiple days in a row. The email also states when the endpoint will be automatically disabled.

Best practices

Respond to the webhook with a 2xx HTTP status code as quickly as possible. Long-running tasks required as a result of the webhook should be deferred using asynchronous processing.
Webhooks can be delivered more than once due to network conditions or retry semantics on our end. You can use the ID in the webhook payload as an idempotency key to ensure you don't process the event more than once.