Webhook URL rules, one-time secrets and machine caps in the API

Webhook URLs

• Each rule is named. Registering or changing a webhook URL that breaks a rule is refused with a 400 whose message names it: the URL must use HTTPS, use a host name rather than an IP address, and not contain a user name or password.
• The host name needs an IPv4 address. A host with only IPv6 (AAAA) records is refused: "Webhook URL must have an IPv4 address". Add an A record.
• Private addresses stay generic. A host that doesn't resolve, and one that resolves to an address that isn't public, get the same answer: "Webhook URL must resolve only to public IP addresses".
• Every rule is checked again before each delivery. A delivery to a URL that breaks one of the first three fails at once, with no retries, and the delivery history names the rule. If the host stops resolving, loses its IPv4 address or resolves to a private address, the delivery is retried, since DNS can change. See URL requirements.

One-time secrets and retries

Four requests return a secret that is shown once: POST /api/v1/webhooks, POST /api/v1/webhooks/{id}/rotate-secret, POST /api/v1/devices and POST /api/v1/devices/{id}/rotate-key.

• A retry never runs twice. A retry under the same Idempotency-Key still never creates a second webhook or device, or rotates a second time.
• It never returns the secret either. Once the first request has succeeded, a retry answers 409 IDEMPOTENCY_CONFLICT (idempotency_secret_not_replayable). If you lost the response, rotate the secret or key again under a new key. See Idempotency.

Machine caps

• A lent machine counts from booking. A machine lent to an organisation counts towards that organisation's plan cap from the moment the hire is booked, even when it starts on a later date.
• An import is refused whole. POST /api/v1/equipment/import/commit that would take you past your cap imports nothing; error.details gives your limit and current count and, for more than one machine, how many the file would add (adding).
• Reactivating a machine out on hire also checks the operating organisation's cap. That refusal is a 422 SUBSCRIPTION_LIMIT_EXCEEDED with no details; its message gives the operating organisation's count and limit, such as "(5 of 5)".

Defects

• A defect holding its machine can't be deleted. DELETE /api/v1/defects/{id} on a defect that is holding its machine out of service answers 409 (defect.delete_blocks_operation). Lift the lockout first.

Unchanged

• Webhook events, payloads and signatures are as before.
• A retry of any other request still returns the first response.