Webhook security
Verify that webhook deliveries come from Higgsfield and were not modified.
Webhook deliveries are signed with the Standard Webhooks scheme. Verify every delivery before you trust its content: anyone who learns your webhook URL can send requests to it.
#How it works
| Header | Content |
|---|---|
webhook-id |
Stable identifier of the event. Redeliveries of the same event reuse it, so you can deduplicate by it. |
webhook-timestamp |
Unix time in seconds when the delivery was signed. Reject deliveries outside a five-minute tolerance. |
webhook-signature |
One or more space-separated v1,<base64> signatures of the raw body. |
The signing secret belongs to the account, personal or organization, and covers every API key and request. Reveal it in Settings in Higgsfield Console; it starts with whsec_. In an organization, only admins can reveal or rotate it. Deliveries are signed from the moment the secret is first revealed.
See Verify signatures for library and manual verification examples.
#Rotate the secret
Rotate the secret in Settings if it may have been exposed. The new secret takes effect immediately and the previous one keeps working for 24 hours. During that window every delivery carries one signature per secret, so you can deploy the new secret without dropping deliveries.
#Endpoint requirements
- The webhook URL must use HTTPS and resolve only to public IP addresses, without credentials in the URL. Other URLs are rejected when the request is submitted.
-
Respond with
2xxwithin ten seconds after durably recording the event. Network failures and5xxresponses are retried;4xxresponses are not. - After a request's data is deleted, no further deliveries are made for it.
Note
Integrations that pass a secret in the webhook request body still receive it in the
X-Webhook-Secret-Keyheader. That header will be retired; switch to signature verification.