Skip to main content
Enterprise API

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 2xx within ten seconds after durably recording the event. Network failures and 5xx responses are retried; 4xx responses 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-Key header. That header will be retired; switch to signature verification.

Was this page helpful?
Navigation