Skip to main content

Manage Webhooks

Read, update or delete a webhook registered with Register Webhook.

Get a Webhook​

GET /webhooks/{id}

curl -X GET \
  https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/webhooks/42 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Success Response (200 OK)​

{
  "webhook": {
    "id": 42,
    "target_url": "https://your-system.example.com/stream/webhooks",
    "events": ["shipment.updated.status", "shipment.updated.waybill"],
    "token": "k3Jd9vQ2mB7xLp0sTn4wZa",
    "status": "active"
  }
}

status is active while deliveries are being made, or failing once Stream has stopped sending after repeated failures.

Update a Webhook​

PUT /webhooks/{id} (or PATCH)

Send the same body as Register Webhook. Both fields are replaced with what you send.

curl -X PUT \
  https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/webhooks/42 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "target_url": "https://your-system.example.com/stream/webhooks-v2",
      "events": ["shipment.updated.status"]
    }
  }'

Success Response (200 OK)​

Returns the updated webhook object. Updating does not change the token and does not reactivate a failing webhook.

Delete a Webhook​

DELETE /webhooks/{id}

curl -X DELETE \
  https://stream-orders-api-sandbox.herokuapp.com/client_api/v2/webhooks/42 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Success Response (200 OK)​

{
  "success": true,
  "error": "",
  "errors": []
}

Error Responses​

404 Not Found​

{
  "success": false,
  "error": "Couldn't find Webhooks::Outgoing::Endpoint with 'id'=42",
  "errors": []
}

422 Unprocessable Entity​

Returned by update when the new target_url or events are invalid, with the same error shapes as Register Webhook.

401 Unauthorized​

Access token is missing or invalid.