This document introduces webhook system for Kakao Login.

Webhook is a feature that sends an HTTP request to the webhook URL set in Kakao Developer to share with the service when there is a change in the account status of a Kakao Login user.

The webhook system is designed based on the Shared Signals and Events Framework(SSF) developed by the OpenID Foundation, with additional event types specifically defined by Kakao.

This document explains the webhook requests that Kakao sends to your service's endpoint. Note that this specification describes incoming webhook requests from Kakao, not API requests that your service makes to Kakao.

For the overall workflow and detailed implementation guide for webhooks, see Implementation steps.

The unlink webhook is a feature where Kakao notifies the service when a user disconnects the app outside the service.

Upon receiving the webhook, the service must process the user's information according to its internal policy and respond with an HTTP status code 200 OK within 3 seconds.

Users who request to unlink outside the service will see a message that the service is no longer available. The unlink webhook is sent after completing the unlink process for the user.

The webhook includes the Service app admin key in the header, and app ID (app_id), user ID (user_id), unlink request source (referrer_type) in the body.

The unlink webhook requires specifying a webhook URL and method, and redirection is not supported. For configuration details, refer to Set unlink webhook.

Unlink webhooks are sent under the following conditions. However, if the service calls the Unlink API to disconnect the app from the user, the unlink webhook will not be sent.

• Unlinking users who have not completed registration.
• When a user disconnects the app via the Kakao Account management page or the Unlink on Manage connected services menu in Kakao Talk.
• When the user deletes their Kakao Account.
• When the app is unlinked due to a customer service request.

The service must respond according to the specified format after perform the necessary tasks upon receiving a webhook. Refer to the steps below.

1. Verify the received webhook using the included Service app admin key and app_id.
2. If the webhook is valid, process the user information corresponding to user_id in the database (DB) by performing deletion, removal, or other actions in accordance with the privacy policy and service policy.
3. Respond with an HTTP status code 200 OK within 3 seconds of receiving the webhook.
   • No body content is required because the success of the response is determined by the HTTP status code.
   • Even if user information processing fails or the user cannot be found, respond with an HTTP status code 200 OK. Perform any additional necessary tasks internally within the service afterward.

To receive an unlink webhook, simulate a scenario where the user disconnects the app. The unlink feature is available on the Kakao Account page or in Kakao Talk via [More] > [Settings] > [Kakao Account]. Use this feature to verify whether the service server processes unlink webhooks correctly.

You must respond with HTTP status code 200 OK within 3 seconds of receiving the webhook request.

Theses are examples of the webhook request that Kakao sends to your service when a user unlinks outside of the service.

curl -v -G GET "{UNLINK_CALLBACK_URL}?app_id=123456&user_id=1234567890&referrer_type=UNLINK_FROM_APPS" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"

curl -v -X POST "{UNLINK_CALLBACK_URL}" \
  -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
  --data-urlencode "app_id=123456" \
  --data-urlencode "user_id=1234567890" \
  --data-urlencode "referrer_type=UNLINK_FROM_APPS"

This is an example of the response your service endpoint should send to Kakao.

HTTP/1.1 200 OK

The account status change webhook sends event information to the specified webhook URL whenever a user's account status changes.

For implementation steps, refer to Implementation steps.

The supported events by category are listed below. Select an event name in the [Event type] column to view the event payload in the event details.

Change events under the CAEP and RISC categories may include sensitive information. Thus, these require configuring the [Kakao Account status change details] consent item and obtaining user consent.

If necessary, follow the steps below:

1. Request for permission to set the consent level for the [Kakao Account status change history] consent item through DevTalk.
   • This permission is granted after a suitability review, so a specific usage scenario must be included when making a request.
2. Once granted, set [Kakao Account status change details] as [Optional Consent] in [Kakao Login] > [Consent Items] on the app management page. Refer to Prerequisites.

• Triggering timing: All tokens issued to a user via Kakao Login expire.
• Required action: Terminate all active service sessions to protect the user account.
• Schema: https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked

• Triggering timing: User links to an app.
• Recommended action: For apps with [Auto-link with an app when logging in] set to [Disabled], complete user registration and perform any other actions required by the service.
• Schema: https://schemas.openid.net/secevent/oauth/event-type/user-linked

• Triggering timing: User unlinks from an app.
• Recommended action: Unlink Kakao Login from the user's account, or delete the user account if Kakao Login is the only authentication method. (Refer to Unlink webhook)
• Schema: https://schemas.openid.net/secevent/oauth/event-type/user-unlinked

• Triggering timing: User consents to a scope via Kakao Login.
• Schema: https://schemas.openid.net/secevent/oauth/event-type/user-scope-consent

• Triggering timing: User withdraws consent for a scope.
• Schema: https://schemas.openid.net/secevent/oauth/event-type/user-scope-withdraw

• Triggering timing: A new business token is issued through Business authentication.
• Recommended action: Store and manage the issued business token information.
• Schema: https://schemas.openid.net/secevent/oauth/event-type/token-issued

See the table below and Payload sample.

Below are SET payload examples for business token events.

{
  "events": {
    "https://schemas.openid.net/secevent/oauth/event-type/token-issued": {
      "subject": {
        "subject_type": "oauth_token",
        "token_type": "access_token",
        "token_identifier_alg": "hash_sha256",
        "token": "base64url(sha256(${TOKEN_VALUE}))"
      },
      "token_subject": {
        "subject_type": "iss-sub",
        "iss": "https://kauth.kakao.com/",
        "sub": "${TOKEN_USER_ID}"
      },
      "token_id": "${TOKEN_ID}",
      "token_class": "business"
    }
  }
}

• Triggering timing: Business token issued through Business authentication is revoked.
• Required action: Stop API calls using the business token.
• Schema: https://schemas.openid.net/secevent/oauth/event-type/token-revoked

See the table below and Payload sample.

• Triggering timing: All business tokens issued to a user are revoked.
• Required action: Stop using all business tokens for the user.
• Schema: https://schemas.openid.net/secevent/oauth/event-type/tokens-revoked

See the table below and Payload sample.

RISC category events require Scope configuration and user consent.

• Triggering timing: Account password is changed.
• Recommended action: Review suspicious activities and decide on necessary follow-up actions.
• Schema: https://schemas.openid.net/secevent/risc/event-type/account-credential-change-required

• Triggering timing: Account is disabled for Kakao Account protection, lock, or usage restriction.
• Required action: If the reason is hijacking, terminate all active sessions to protect the user account. If the reason is bulk-account, analyze user activity and determine necessary follow-up actions.
• Schema: https://schemas.openid.net/secevent/risc/event-type/account-disabled

• Triggering timing: Account is enabled. When a Kakao Account is recovered from dormant or hijacked state.
• Recommended action: Re-enable account recovery via Kakao Login and registered Kakao Account email.
• Schema: https://schemas.openid.net/secevent/risc/event-type/account-enabled

• Triggering timing: Account is deleted.
• Recommended action: Delete the user account or provide alternative login methods.
• Schema: https://schemas.openid.net/secevent/risc/event-type/account-purged

• Triggering timing: Credential compromise is detected. When Kakao Account credentials are suspected of being compromised. (Example: successful login from a suspicious new environment)
• Recommended action: Review suspicious activities and decide on necessary follow-up actions.
• Schema: https://schemas.openid.net/secevent/risc/event-type/credential-compromise

• Triggering timing: Identifier is changed. When the user's email address or phone number is updated.
• Recommended action: Delete the old phone number or email address, and update the records with the new identifier.
• Schema: https://schemas.openid.net/secevent/risc/event-type/identifier-changed

• Triggering timing: Identifier is no longer available. When a Kakao Account's email or phone number is reused by another user, causing the previous identifier to expire (Expired) or be suspended (Suspended).
• Recommended action: Stop using the user's email and phone number in the service, and directly collect new email and phone number information from the user.
• Schema: https://schemas.openid.net/secevent/risc/event-type/identifier-recycled

• Triggering timing: All sessions are terminated. When existing devices are logged out after a password change.
• Required action: Terminate all active sessions to protect the user account.
• Schema: https://schemas.openid.net/secevent/risc/event-type/sessions-revoked

CAEP category events require Scope configuration and user consent.

• Triggering timing: Authentication security level is changed. When security level changes such as two-factor authentication setup.
• Recommended action: Verify the user meets the authentication security level required for the service, and re-authenticate if necessary before providing the service.
• Schema: https://schemas.openid.net/secevent/caep/event-type/assurance-level-change

• Triggering timing: Account password is changed. When a password is reset or a Kakao certificate is reissued.
• Schema: https://schemas.openid.net/secevent/caep/event-type/credential-change

• Triggering timing: User Kakao Account information is changed. Notified only when information the user consented to provide is changed.
• Recommended action: Call the Retrieve user information API and update with the changed information.
• Schema: https://schemas.kakao.com/platevent/kakao/event-type/user-profile-changed

The service receives a SET (Security Event Token) containing change event information of the Kakao Account through the POST method.

Below is an example of the request that is delivered to the webhook URL. Content-Type of the webhook request header is application/secevent+jwt, and the body is a SET value containing the change event information. SET is a JWT (JSON Web Token) type token and consists of the three parts.

POST /kakao/events HTTP/1.1
Host: callback.example.com
Content-Type: application/secevent+jwt
Accept: application/json

eyJraWQiOiI2NjVhYmVlYzExOGRkZmMyZDNiZjNlMmFkYWU3OT...

The SET is generated as a single string of three parts that are Base64-encoded and concatenated with the period (.). The contents can be verified by Base64-decoding after separating each part based on the period. After SET validation, the service can verify the payload contents to perform any necessary user account protection actions. Below is an example of a decoded SET header and payload.

{
  "kid": "665abeec118ddfc2d3bf3e2adae799",
  "typ": "secevent+jwt",
  "alg": "RS256"
}

Below are the details of the fields in the Header and Payload.

The service must check and validate the contents of the SET before performing user account protection actions based on change event information. You can check and verify the SET contents in the following order:

1. Separate the header, payload, and signature based on the period (.).
2. Decode the payload in Base64.
3. Verify that the iss value in the payload matches https://kauth.kakao.com.
4. Verify that the aud value in the payload matches the service app's REST API key.
5. Verify the signature

Signature verification proceeds in the following order.

1. Decode the header in Base64.
2. Request OIDC: Get public key to get the list of public keys used by the Kakao authentication server for signing.
3. Check the public key value corresponding to the kid of the header in the public key list.
   • Caching the public key for a certain period is recommended, and note that requests may be blocked if they are too frequent.
4. Verify the signature with the public key using a library that supports JWT signature verification.
   • Note: OpenID Foundation, jwt.io
   • When implementing signature verification directly without using a library, the signature verification process can be performed according to the RFC7515 specification.

If the SET receiving server receives a webhook request via the webhook URL and the SET validation is successful, you should respond with the HTTP response code 202 Accepted with no response body. See the example below.

HTTP/1.1 202 Accepted

If the SET receiving server fails to validate the SET after receiving the webhook, you must respond within 3 seconds using the following format:

• HTTP status code: 400 Bad Request
• Header: Content-Type: application/json
• Body: In JSON format, including the error code (err) and reason (description) as specified in the RFC8935 standard.

// HTTP/1.1 400 Bad Request
// Content-Type: application/json
{
  "err": "invalid_key",
  "description": "Key ID 12345 has been revoked."
}

You can retrieve the Account status change webhook specification.

curl -X GET https://kauth.kakao.com/.well-known/ssf-configuration

// HTTP/1.1 200
{
  "issuer": "https://kauth.kakao.com",
  "jwks_uri": "https://kauth.kakao.com/.well-known/jwks.json",
  "delivery_methods_supported": "http://schemas.openid.net/secevent/risc/delivery-method/push"
}

You can try sending webhooks to see if webhooks work normally in [Tools] > [Webhook Test]. See Account status change webhook test for more details.