Identity sync hooks during sign-in
Extend SAML assertions or OIDC claims with a synchronous hook, understand failure behaviour, and inspect call results before relying on it.
A sync hook calls a service you control while the platform is preparing a SAML assertion or OIDC claims for an application. This is useful when sign-in needs additional information or a decision from your own system. Because sign-in waits for the call, a slow or unavailable hook can affect a person trying to open an application. Choose this mechanism only when the application needs the result during sign-in.
Choose the right kind of hook
Identity → Sync hooks is different from an asynchronous event notification. An event hook tells another system that something happened; it does not normally need to hold the sign-in open. A sync hook participates in issuance of an assertion or claims. Use the SAML assertion kind for the corresponding SAML flow and the OIDC claims kind for the corresponding OIDC flow. Do not use a sync hook just to copy routine account events to another system.
Configure a controlled endpoint
Create a hook with a recognisable name, its kind, an HTTPS endpoint, a timeout and the intended application scope. Check the application identifiers carefully. Review the scope before saving rather than assuming an empty list means one application. The endpoint handles live sign-in information, so restrict access to its logs and implement the documented request verification and response format.
When a signing secret is shown after creation or rotation, store it in your approved secret store and configure the receiving service. Do not paste it into application source, screenshots or tickets. Coordinate rotation with the receiving service; a new secret must be recognised before you rely on subsequent calls. The console provides secret rotation because credentials need their own lifecycle, separate from the hook’s display name.
Decide what a failure should do
The failure mode controls whether the sign-in path can continue when the hook cannot complete as required. Open favours continued access without the unavailable enrichment. Closed can refuse the affected sign-in. Neither choice is universally right: a hook that supplies an optional display value has different requirements from a hook that performs a mandatory business check. Discuss this with the application owner and arrange a tested recovery path before enabling a closed mode.
Test and inspect actual calls
Use the test-call control and read its outcome and duration. Inspect the hook’s call history for timeouts, refusals or invalid responses. A successful test call shows that the test completed; it does not prove that every application is correctly scoped or that every real sign-in will pass. Test a controlled account with the intended application and check both its sign-in result and the receiving service’s record.
Recover from a broken hook
If a newly enabled hook disrupts sign-in, an authorised administrator can disable it while correcting the endpoint. Review the effect of disabling a mandatory check with the application owner. Deleting a hook removes its configuration and should not be the first troubleshooting step when preserving settings would help. Hook management and call history have separate read and write permissions. When requesting help, include the hook reference, application, failure time and outcome; exclude signing secrets, tokens and assertion contents.