Developer API and Webhooks
API tokens are hotel-scoped, ability-scoped, rate-limited, and audited. Keep the API disabled until the integration owner, purpose, and data boundaries are documented.
Create a token safely
- Create a dedicated integration identity; never reuse an employee token.
- Select only the abilities needed, such as read availability or create reservations.
- Copy the token once into a secret manager. Do not place it in source code, screenshots, chat, or documentation.
- Test against a non-production hotel and confirm tenant isolation.
- Record the owner and rotation date, then revoke the token when the integration ends.
| Field | Guidance |
|---|---|
| Name | Describe the consumer, for example “Website booking sync”. |
| Abilities | Choose the smallest read/write scope needed. |
| Expiry/rotation | Use the shortest practical lifetime and rotate on schedule. |
| Webhook secret | Store privately and verify every incoming signature. |
Webhook delivery
Subscriptions can deliver hotel events to an HTTPS endpoint. The receiver should verify the signature, return a fast success response, and process the event idempotently. Use the delivery log to inspect status, attempts, response code, and next retry.
Failure recovery
- Do not blindly resend until the receiver is idempotent.
- Compare event ID and payload hash before processing a retry.
- Fix DNS, TLS, authentication, or receiver errors, then retry the specific delivery.
- Use
php artisan hotel:webhook-retryfor scheduled retry processing. - Revoke a token immediately if its value may have leaked.
Production boundary: API responses and webhooks may contain guest data. Use HTTPS, restricted credentials, retention limits, and access logs.