Use this endpoint to register a webhook URL for your tenant or to replace an existing one. Every time you call this endpoint, Idem generates a new signing secret and associates it with the URL you provide. The raw secret is included in the response exactly once — use it to verify the authenticity of incoming webhook payloads on your server. If you call this endpoint again to update the URL, a new secret is issued and the previous one is immediately invalidated.
Endpoint
Authorization
Requires an API key with WEBHOOK_MANAGE scope.
The webhook signing secret is returned only once in the response to this request. Store it securely in your application’s secret management system immediately. If you lose the secret, you must call this endpoint again to rotate it — all existing payloads signed with the old secret will fail verification from that point forward.
Request Body
The HTTPS URL that Idem will POST event payloads to. Must be a non-empty, publicly reachable URL. URLs pointing to private IP ranges, localhost, or known disallowed domains will be rejected.
Request Example
Response
The webhook URL that was registered, as provided in the request.
The raw signing secret for this webhook configuration — a 64-character hex string with no prefix. Shown only once. Use this value to validate the X-Idem-Signature header on incoming webhook requests.
Response Example
Validate every incoming webhook by computing an HMAC-SHA256 signature over the raw request body using your stored secret and comparing it to the X-Idem-Signature header. Reject any request where the signatures do not match.
Error Codes
