> For the complete documentation index, see [llms.txt](https://codehas.gitbook.io/the-repairbox/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codehas.gitbook.io/the-repairbox/webhooks-and-notifications.md).

# Webhooks and Notifications

RepairBox uses event-driven behavior for notifications and integrations. A notification sends information to a person through a channel such as email, SMS, or WhatsApp. A webhook sends an event payload to a system endpoint, or receives an event from an external provider. These are related but not interchangeable mechanisms.

The exact outbound webhook management UI, event catalogue, delivery log, and retry controls depend on the deployed RepairBox version. This page explains the expected concepts and security requirements. Do not assume a specific event name or endpoint exists until it is confirmed in the current API/integration documentation.

## 1. Webhook directions

### Outbound RepairBox webhook

RepairBox informs another service when a supported event occurs. For example, an integration might need to know that a repair order was created, a repair item changed status, an estimate was approved, or a payment record was reconciled. Only configure events the deployed version actually emits.

A typical flow is:

1. An authorized business action or system event occurs.
2. RepairBox prepares an event payload from the committed record.
3. The integration signs or otherwise authenticates the webhook where supported.
4. RepairBox delivers the payload to the configured HTTPS endpoint.
5. The receiver validates the signature, acknowledges receipt, and deduplicates the event.
6. The receiver processes the event and records its outcome.

### Inbound provider webhook

An external service calls RepairBox when its state changes. Examples include a Stripe payment event, an SMS delivery callback, or a WhatsApp message/status callback. Each provider uses its own event model and authenticity check. Do not require or trust a generic RepairBox bearer token as a substitute for provider-specific signature validation.

## 2. Notifications versus webhooks

| Mechanism                       | Main recipient               | Intended result                                           | Important safeguard                                     |
| ------------------------------- | ---------------------------- | --------------------------------------------------------- | ------------------------------------------------------- |
| Email/SMS/WhatsApp notification | Customer or staff member     | Human-readable update                                     | Correct recipient, preference/consent, safe template    |
| Outbound webhook                | External application/server  | Machine-readable event                                    | Signing, retries, idempotency, event versioning         |
| Inbound provider webhook        | RepairBox endpoint           | Update integration state, such as delivery/payment status | Provider signature verification and event deduplication |
| Internal event/listener/job     | RepairBox component or queue | Decouple business changes from side effects               | Transaction consistency and duplicate-safe processing   |

A notification being sent does not prove a webhook succeeded. A webhook succeeding does not prove a customer notification was delivered.

## 3. Define a useful event contract

For each outbound webhook event supported by RepairBox, document:

* **Event name/type:** stable, descriptive identifier.
* **Event ID:** unique delivery/event identifier for deduplication.
* **Event version:** contract version so payload changes can be managed safely.
* **Occurred time:** timestamp with an explicit timezone/format.
* **Business/outlet context:** only the scope the receiver needs.
* **Resource reference:** stable RepairBox public/human reference or documented resource ID.
* **Changed fields or snapshot:** include only the fields needed to describe the event.
* **Delivery attempt:** track internally rather than making the receiver depend on an attempt number as business data.
* **Documentation:** define required, optional, and nullable fields and their meanings.

Example conceptual payload, not a promise of the deployed schema:

```
{
  "id": "evt_example_unique_id",
  "type": "repair.item.status_changed",
  "version": 1,
  "occurred_at": "2026-10-12T10:30:00Z",
  "data": {
    "repair_reference": "REP-2026-000125",
    "item_reference": "ITEM-EXAMPLE",
    "status": "quality_check",
    "outlet_reference": "OUTLET-EXAMPLE"
  }
}
```

Consumers must use the actual schema published by the deployed API/integration rather than assuming the example fields, identifiers, or event name match production.

## 4. Select events conservatively

A RepairBox integration could need event families such as:

* Repair intake or repair-order creation.
* Repair-item assignment or reassignment.
* Repair/item status change.
* Estimate created, submitted, approved, rejected, or revised.
* Invoice created/updated or payment reconciled.
* Quality-control result.
* Notification delivery outcome.
* Customer or catalog changes, if explicitly supported and appropriate.

Use only the events the installation exposes and only when the external consumer has a valid need. Avoid subscribing to every event by default. A consumer that only needs completion status should not receive customer profile updates, private diagnostics, or financial data.

For each event, record the trigger point and business meaning. For example, “payment record created” and “payment confirmed as successful” are distinct events. Likewise, “one repair item ready” is not equivalent to “entire repair order completed.”

## 5. Configure an outbound destination

Where RepairBox exposes an outbound webhook configuration, the destination generally needs:

* **Name/label:** meaningful owner/system name.
* **Endpoint URL:** a stable, HTTPS endpoint controlled by the recipient.
* **Subscribed events:** only the required event types.
* **Secret/signing key:** unique secret used to authenticate webhook deliveries where the platform supports signing.
* **Enabled state:** ability to pause a broken or compromised destination if supported.
* **Timeout/retry policy:** bounded attempts with backoff appropriate to the event.
* **Destination ownership:** a technical contact responsible for endpoint health.
* **Last delivery/status:** operational visibility if supported.
* **Rotation procedure:** replace the signing secret without losing event delivery.

These are configuration concepts, not a guarantee that the current UI contains every listed field. Avoid sending to user-submitted URLs without a policy to prevent server-side request forgery, private-network targets, and unauthorized data exfiltration.

## 6. Signatures and request verification

A receiving system must be able to determine that the event came from the expected sender and has not been modified. Use the exact signature scheme documented by the provider/platform.

For a signed outbound webhook, the sender commonly computes a message authentication code over the raw request body, often including timestamp context. The receiver should verify it using constant-time comparison and the secret configured for that destination.

For an inbound Stripe webhook, use Stripe's official signature-verification method and endpoint-specific signing secret. For SMS/WhatsApp providers, follow their signature or verification procedure.

Do not:

* Trust a field in the JSON body that merely says the sender is RepairBox.
* Parse and re-serialize JSON before verifying a signature that is calculated over the raw body.
* Use a browser-exposed secret.
* Accept all requests when signature verification fails.
* log the signing secret or complete sensitive headers.
* assume one provider's signature algorithm applies to another provider.

Webhook URLs should use HTTPS. Keep production and testing secrets separate and define a rotation path.

## 7. Retries, idempotency and ordering

Webhook delivery is normally at-least-once rather than a guarantee of exactly-once processing. A receiver may see the same event multiple times because the sender did not receive an acknowledgement, a network timed out, or a delivery retry was triggered.

Recommended receiver behavior:

1. Validate request authenticity.
2. Validate the payload structure and supported event version.
3. Store the event ID or a provider-specific unique identifier.
4. If that event has already been processed, acknowledge it without repeating the business action.
5. Acknowledge quickly after durable receipt, then do heavier work asynchronously if possible.
6. Handle events that arrive out of order by checking current authoritative state/version/timestamp rather than assuming arrival order.
7. Retry transient failures with bounded exponential backoff and jitter.
8. Send permanent failures to a dead-letter/review queue where the architecture supports it.

Do not make every event handler repeat a payment, create a duplicate repair, or send a duplicate customer message. Idempotency should be implemented in the actual side effect, not only in the webhook receiver's HTTP response.

## 8. Inbound payment and messaging callbacks

### Stripe

Validate the Stripe signature, identify the event type and associated provider object, reconcile it against the stored RepairBox payment attempt, and process duplicates safely. Payment state must not rely only on the customer's browser return. See Stripe Integration.

### SMS providers

Validate callbacks according to the chosen provider's documentation and map provider message IDs to the corresponding RepairBox notification attempt. Keep sent, delivered, failed, and unknown statuses distinct when the provider reports them. See SMS Configuration.

### WhatsApp

Verify the callback against the configured provider/business account and validate inbound messages or status objects before linking them to a customer or notification. See WhatsApp Configuration.

### Other providers

Every provider can have distinct authentication headers, callback challenge, retry timing, signature scope, event names, and response requirements. Use that provider's official specification.

## 9. Link events to notifications without loops

A repair status update may trigger a customer notification and an outbound webhook. That webhook may cause an external system to update a record, which may send an update back to RepairBox. Without origin tracking and idempotency, this can create a loop.

To control loops:

* Track the originating system/event where supported.
* Avoid treating a sync echo as a new user-originated change.
* Compare meaningful state/version before writing updates back.
* Ensure notifications fire only for intended state transitions, not every repeated save.
* Use deduplication keys for each logical customer message.
* Do not trigger financial side effects from unverified third-party state.
* Test bi-directional sync with two systems before enabling it on live data.

## 10. Payload privacy and data minimization

Treat webhooks as data exports. An external endpoint receives the fields included in each payload, and a compromised endpoint may expose them.

* Send minimum necessary fields.
* Avoid unnecessary email addresses, phone numbers, street addresses, notes, attachments, estimates, or invoice lines.
* Never include passwords, device unlock codes, bearer tokens, card details, or secrets.
* Apply the destination's outlet/business scope.
* Document the data owner, retention, and deletion process.
* Restrict who can configure destinations and inspect payload logs.
* Redact sensitive details in logs and dashboards.
* Review the receiver's security, HTTPS certificate, access control and incident process.
* Do not send a full internal API resource simply because it is convenient.

If a webhook destination is controlled by a third party, obtain approval for the data fields and purpose before enabling it.

## 11. Operations and monitoring

Where the application offers delivery history, monitor:

* Delivery success/failure rate.
* Most recent successful delivery.
* HTTP response code and bounded response details.
* Attempt count and next retry time.
* Destination timeout/latency.
* Signature/validation failure count for inbound callbacks.
* Duplicate event count.
* Queue depth and failed-job count.
* Provider event/message IDs for reconciliation.

Avoid logging credentials, full signatures, authorization headers, or full request bodies containing customer information. Define an alert threshold and an owner for failed delivery. A webhook marked “failed” may not be retried automatically; verify the installed behavior and use the supported replay/retry process.

## 12. Test cases

Before production, test:

* A valid signed event and an invalid signature.
* A replayed/duplicate event.
* A timeout after the receiver commits work but before the response reaches the sender.
* Temporary 5xx/network failure and eventual recovery.
* Permanent 4xx/validation failure.
* Unsupported event type or schema version.
* Out-of-order repair item status events.
* Wrong outlet or resource references.
* Provider payment event for unknown or mismatched invoice.
* A notification event that is intentionally disabled.
* A callback with missing fields or oversized payload.
* A receiver endpoint that redirects or resolves to a prohibited/private network if destination validation is part of the sender's configuration process.

## 13. Troubleshooting

**No webhook arrives:** verify the event is emitted by this version, destination URL is reachable over HTTPS, correct event subscriptions are enabled, and queues/listeners are running.

**Receiver returns repeated errors:** inspect the response code and bounded error text, timeout, payload schema, receiver logs, and provider delivery history. Return a successful acknowledgement only after the event has been durably accepted.

**Signature validation fails:** verify the correct destination-specific secret, request body handling, header names, clock/timestamp tolerance where applicable, and environment. Never bypass signature checks as a permanent fix.

**Duplicate business action occurs:** add durable event-ID deduplication and idempotent side effects; then reconcile existing duplicate records safely.

**Events arrive out of order:** check event timestamps/versions and read current RepairBox state before applying the change. Do not assume delivery order equals occurrence order.

**Status changes trigger a loop:** identify origin metadata and repeated-write behavior; ignore sync echoes where appropriate and make state transitions idempotent.

**Sensitive data appears in the payload:** pause the destination if needed, minimize the payload at the server/resource boundary, rotate any exposed secrets, and follow the incident process.

## 14. Go-live checklist

* [ ] Direction is clear: outbound RepairBox event or inbound provider callback.
* [ ] The exact event types and payload schema are documented.
* [ ] Only required destinations and fields are enabled.
* [ ] HTTPS and the correct signature/verification scheme are in place.
* [ ] Duplicate event processing and retry behavior are safe.
* [ ] Out-of-order delivery and asynchronous processing have been tested.
* [ ] Payment and messaging callbacks map to the correct records.
* [ ] No secrets or unnecessary personal information appear in payloads/logs.
* [ ] Delivery monitoring and an owner for failures exist.
* [ ] A destination disable/revoke and secret rotation process is documented.

## Related documentation

* Notification Settings
* Email Configuration
* SMS Configuration
* WhatsApp Configuration
* Stripe Integration
* API Authentication
* API Endpoints
