Overview
Outbound webhooks let external systems (Slack, ERPs, custom scripts) react to platform events — asset created, transferred, retired, maintenance completed. A management UI is planned ([FE-12]). No webhook infrastructure exists.
What to Build
A WebhooksModule in backend/src/webhooks/:
Entities: WebhookSubscription (id, url, events string array, secret, isActive, createdBy, createdAt) and WebhookDelivery (id, subscription, event, payload jsonb, statusCode, attempt, deliveredAt).
| Method |
Path |
Description |
POST |
/api/webhooks |
Register a subscription (ADMIN) |
GET |
/api/webhooks |
List subscriptions with recent delivery status |
PATCH |
/api/webhooks/:id |
Update URL/events/active |
DELETE |
/api/webhooks/:id |
Remove |
POST |
/api/webhooks/:id/test |
Send a test event |
Delivery: an injectable WebhookEmitter.emit(event, payload) called from asset lifecycle points; deliveries POSTed with an HMAC-SHA256 signature header (X-AssetsUp-Signature) computed with the subscription secret; 3 retries with backoff via the Bull queue ([BE-22]); deliveries recorded.
Initial events: asset.created, asset.updated, asset.deleted, asset.transferred, asset.status_changed, maintenance.completed.
References
- Prior art:
git show f28e3f8~1 -- backend/src/webhooks/
- Blocked by [BE-06], [BE-22]
Acceptance Criteria
Overview
Outbound webhooks let external systems (Slack, ERPs, custom scripts) react to platform events — asset created, transferred, retired, maintenance completed. A management UI is planned ([FE-12]). No webhook infrastructure exists.
What to Build
A
WebhooksModuleinbackend/src/webhooks/:Entities:
WebhookSubscription(id,url,eventsstring array,secret,isActive,createdBy,createdAt) andWebhookDelivery(id,subscription,event,payloadjsonb,statusCode,attempt,deliveredAt).POST/api/webhooksGET/api/webhooksPATCH/api/webhooks/:idDELETE/api/webhooks/:idPOST/api/webhooks/:id/testDelivery: an injectable
WebhookEmitter.emit(event, payload)called from asset lifecycle points; deliveries POSTed with an HMAC-SHA256 signature header (X-AssetsUp-Signature) computed with the subscription secret; 3 retries with backoff via the Bull queue ([BE-22]); deliveries recorded.Initial events:
asset.created,asset.updated,asset.deleted,asset.transferred,asset.status_changed,maintenance.completed.References
git show f28e3f8~1 -- backend/src/webhooks/Acceptance Criteria