Webhook Events

Ory Polis uses webhooks to notify your application any time changes are made to the connections. We'll notify you of the following 4 events for each connection.

The sso.created event carries the connection's clientSecret, so that an application learns the credentials of a connection created through the Admin Portal or a setup link. The secret authenticates the token exchange for the connection and authorizes updating or deleting it, so treat the webhook endpoint and anything that stores its requests as holding a secret. The other events name the connection by its clientID only; fetch the connection through the API if you need its secret then.

Delivery

Events are delivered on a best-effort basis. Ory Polis sends each event once the change is saved, while the request that made it is still being handled. When the webhook answers with anything other than a 2xx status code, or not at all within 20 seconds, the request is retried up to 3 times, 3 seconds apart. If every attempt fails, the event is dropped:

• The change itself is kept, and the request that made it succeeds.
• The failure is logged, and recorded as a failed webhook.delivery in its event_type="connection" series, so you can alert on it, with a log record that names the event.
• The event is not queued or sent again later, and events from separate requests may arrive in any order.

A webhook that is slow or down therefore delays the request that made the change, by up to about a minute and a half. Treat the events as notifications, not a log you can rebuild state from: to know which connections exist now, ask the API.

Events

sso.created - New connection has been created.

{
  "event": "sso.created",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "name": "SSO Connection",
    "description": "SSO Connection for Ory Corp",
    "clientID": "326991705d478f0178fc2b49e35cd166dc771061",
    "clientSecret": "15b2db91b2ba4c848b68148f108035e7138d69104d99de89",
    "provider": "saml.example.com",
    "friendlyProviderName": null
  }
}

sso.deactivated - A connection has been deactivated.

{
  "event": "sso.deactivated",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "name": "SSO Connection",
    "description": "SSO Connection for Ory",
    "clientID": "326991705d478f0178fc2b49e35cd166dc771061",
    "provider": "saml.example.com",
    "friendlyProviderName": null
  }
}

sso.activated - A connection has been activated.

{
  "event": "sso.activated",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "name": "SSO Connection",
    "description": "SSO Connection for Ory",
    "clientID": "326991705d478f0178fc2b49e35cd166dc771061",
    "provider": "saml.example.com",
    "friendlyProviderName": null
  }
}

sso.deleted - A connection has been deleted.

{
  "event": "sso.deleted",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "name": "SSO Connection",
    "description": "SSO Connection for Ory",
    "clientID": "326991705d478f0178fc2b49e35cd166dc771061",
    "provider": "saml.example.com",
    "friendlyProviderName": null
  }
}

Configure Webhook

To configure the webhook, you have to set the following environment variables.

• WEBHOOK_URL - The URL to which the webhook events will be sent.
• WEBHOOK_SECRET - The secret key used to sign the webhook events.