Enable Webhooks

Activate webhooks in your Developer settings to start receiving real-time event notifications.

Add Endpoint

Register your webhook endpoint and select which events you want to receive.

Test & Monitor

Send test events, view delivery attempts, and monitor webhook status in the dashboard.

​
Enabling Webhooks

1

Enable Developer API

Go to the Developer page in your Roastify dashboard and enable the Developer API.

2

Enable Webhooks

Once the Developer API is enabled, click Enable Webhooks to access the webhook portal.

3

Create Endpoint

In the webhook portal, click New Endpoint and enter your endpoint URL. Select the event types you want to receive.

​
Adding & Testing Endpoints

1

Add Your Endpoint

Enter your endpoint URL and select the events you want to listen for. If you don’t specify any, you’ll receive all events by default.

2

Use Svix Play (Optional)

If your endpoint isn’t ready, use a temporary Svix Play URL to inspect incoming webhooks before going live.

3

Test Delivery

Use the Testing tab in the dashboard to send sample events and verify your endpoint is working. You can view payloads, delivery attempts, and status for each test.

​
Webhook Events

Roastify sends the following webhook events related to order fulfillment and tracking:

Event TypeDescription
fulfillment.createdSent when a fulfillment is created
fulfillment.canceledSent when a fulfillment is canceled
fulfillment.cancelation_requestedSent when a fulfillment cancelation is requested
fulfillment.declinedSent when a fulfillment is declined
fulfillment.packagedSent when a fulfillment is packaged
fulfillment.pickedSent when a fulfillment is picked
fulfillment.printedSent when a fulfillment is printed
fulfillment.shippedSent when a fulfillment is shipped
tracking.updatedSent when tracking information is updated

Below are example payloads for each event:

fulfillment.created
{
  "eventType": "fulfillment.created",
  "orderId": "ord_12345",
  "status": "created",
  "updatedAt": "2024-06-01T12:34:56Z"
}
fulfillment.canceled
{
  "eventType": "fulfillment.canceled",
  "orderId": "ord_12345",
  "status": "canceled",
  "updatedAt": "2024-06-01T12:34:56Z"
}
fulfillment.cancelation_requested
{
  "eventType": "fulfillment.cancelation_requested",
  "orderId": "ord_12345",
  "status": "cancelation_requested",
  "updatedAt": "2024-06-01T12:34:56Z"
}
fulfillment.declined
{
  "eventType": "fulfillment.declined",
  "orderId": "ord_12345",
  "status": "declined",
  "updatedAt": "2024-06-01T12:34:56Z"
}
fulfillment.packaged
{
  "eventType": "fulfillment.packaged",
  "orderId": "ord_12345",
  "status": "packaged",
  "updatedAt": "2024-06-01T12:34:56Z"
}
fulfillment.picked
{
  "eventType": "fulfillment.picked",
  "orderId": "ord_12345",
  "status": "picked",
  "updatedAt": "2024-06-01T12:34:56Z"
}
fulfillment.printed
{
  "eventType": "fulfillment.printed",
  "orderId": "ord_12345",
  "status": "printed",
  "updatedAt": "2024-06-01T12:34:56Z"
}
fulfillment.shipped
{
  "eventType": "fulfillment.shipped",
  "orderId": "ord_12345",
  "status": "shipped",
  "carrier": "UPS",
  "trackingNumber": "1Z999AA10123456784",
  "trackingUrl": "https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784",
  "updatedAt": "2024-06-01T12:34:56Z"
}
tracking.updated
{
  "estimatedDelivery": "2024-06-05T17:00:00Z",
  "shippingCarrier": "UPS",
  "shippingService": "Ground",
  "shippingStatus": "in_transit",
  "trackingNumber": "1Z999AA10123456784",
  "trackingUrl": "https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784"
}

​
Signature Verification

1

Get Your Secret

Each endpoint has a unique secret key. Find it in the endpoint details in the dashboard.

2

Verify Signature

Use the official Svix libraries to verify the signature and timestamp of incoming webhooks. Always use the raw request body for verification.

3

Sample Code (JavaScript)

Signature Verification Example
import { Webhook } from "svix";

const secret = "whsec_..."; // Your endpoint's secret
const headers = {
"svix-id": req.headers["svix-id"],
"svix-timestamp": req.headers["svix-timestamp"],
"svix-signature": req.headers["svix-signature"],
};
const payload = req.body; // Use the raw request body

const wh = new Webhook(secret);
try {
const verified = wh.verify(payload, headers);
// Process the verified payload
} catch (err) {
// Invalid signature
res.status(400).send("Invalid signature");
}

For more details and code samples in other languages, see the Svix signature verification docs.

Retry Schedule

Webhook deliveries are retried automatically using an exponential backoff schedule:

  • Immediately
  • 5 seconds
  • 5 minutes
  • 30 minutes
  • 2 hours
  • 5 hours
  • 10 hours (twice)

You can also manually retry messages from the dashboard. If an endpoint is removed or disabled, delivery attempts will stop.

Troubleshooting & Recovery

Common issues:
  • Not using the raw payload body for signature verification
  • Using the wrong secret key (keys are unique per endpoint)
  • Sending the wrong HTTP response codes (must be 2xx for success)
  • Response timing out (must respond within 15 seconds)

If your endpoint fails for 5 days, it will be disabled. To re-enable, visit the dashboard and select “Enable Endpoint”. You can also replay failed messages from the dashboard, either individually or in bulk for a given time window.
For more tips, see the Svix troubleshooting guide.