Webhooks

ReReady can send your app real-time updates about your device returns, so you know when to follow up with an employee, prepare for a device delivery, etc. Available for Enterprise accounts only.

What are webhooks?

Webhooks are HTTP POST requests that ReReady makes to the URL of your choice. These requests include a JSON-formatted payload with details about a transaction. These requests occur when ReReady updates a transaction to one of the webhook-enabled transaction statuses.

How do I configure webhooks?

You can add up to 3 webhook endpoints per company. To add a webhook endpoint:

1. Log in to your ReReady account (or open a free account).
2. Click the "Settings" button at the top.
3. Click the "Company settings" button at the top.
4. If you haven't already, click "Enable Enterprise service".
5. Click to 'Manage webhooks"
6. Click to create a new webhook endpoint.

What do the JSON payloads look like?

Here is an example JSON payload that would be posted to your webhook endpoint:

{
  "device_return_id": "e025d043-c41d-4167-8bd3-24cc66345696",
  "serial_number": null,
  "state": "pending_return_shipment",
  "test": false,
  "ticket_url": null,
  "url": "https://www.reready.co/device_returns/e025d043-c41d-4167-8bd3-24cc66345696"
}

What are the possible states?

These are the "state" values you might receive via webhooks, and their meanings:

1. pending_outbound_shipment: Waiting for fulfillment of the empty box.
2. pending_outbound_shipment_delivery: Waiting on the empty box to be delivered.
3. pending_return_shipment: Waiting on the employee to return the device.
4. pending_return_shipment_delivery: Waiting for the device to be delivered.
5. failed: Not completable due to carrier failure, incorrect address, etc.
6. not_returned: Employee failed to return the device.
7. complete: Successfully returned.

Can webhook payloads be verified?

Yes, all webhook payloads are signed so you can verify them. You should use your webhook's "signing secret key" to generate your own HMAC, and compare it to ReReady's HMAC included with each webhook payload. Here's how it works:

• Get your webhook's "signing secret key".
  Go to Account > Webhooks, select a webhook, then click to show the value. It starts with ssk_.
• Get the timestamp and ReReady's HMAC.
  When your app receives a webhook payload from ReReady, get the value of the X-ReReady-Signature-512 header. (It looks like t=1744831201,v=feef24d027ff220621619db8cc1522abb4426679540c7b107a0dc8f19650c2bfa5faf5a866ffba2d0a108e0e0f1e5d9a2368d5593177be943ce10132cbbb8cbd.) Split the string by comma (,) to get the key-value pairs. The t key represents the Unix timestamp. The v key represents ReReady's HMAC.
• Build your HMAC.
  Build your HMAC using the SHA512 algorithm with hexdigest formatting. For example, in Ruby you should use OpenSSL::HMAC.hexdigest('SHA512', key, data). The "key" is your your webhook's "signing secret key". The "data" is created by concatenating the Unix timestamp, a dot/period character (.), and the JSON string from the webhook payload.
• Compare your HMAC against ReReady's HMAC.
  If the HMAC strings don't match, the webhook payload may not be legitimate.

If verifying the signature exceeds your technical capabilities, there is a simpler but less secure alternative. You can add a token parameter to the endpoint URL you enter in ReReady, with a random value that you generate. Then when you receive a webhook payload from ReReady, you check to confirm the token parameter has the value you generated. If the strings don't match, the webhook payload may not be legitimate.

Can webhook endpoints be tested?

Yes, you can simulate webhook . Navigate to your webhook endpoint in ReReady, then click the "Test" button. For each test you can select which state you want to POST to your endpoint.

Can the last webhook results be viewed?

Yes, you can always view the results of the last request ReReady made to you webhook endpoint. Navigate to your webhook endpoint in ReReady and see the "last used" information, including:

• Time
• Return number
• Return state
• Response status your endpoint returned