Webhook

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.

Before you begin

Check the Usage policy before using the webhook.

Unlink webhook

Basic information

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.

Prerequisites

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

Conditions for sending unlink webhooks

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.

Actions upon receiving a webhook

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.

Testing the unlink webhook

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.

Request

Header

Parameter

Response

• HTTP status code 200 OK (within 3 seconds)

Sample

Request: GET method

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}"

Request: POST method

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"

Response

HTTP/1.1 200 OK

Account status change webhook

Basic information

The Account status change webhook feature notifies your pre-registered webhook URL of significant changes to a user's account, such as app link or unlink, password changes, or account deactivation. By receiving theses webhooks, your service can take necessary actions, such as terminating sessions or requiring user reauthentication, to enhance security.

When a user's change event occurs, the change event information is delivered as an HTTP POST request to the service's webhook URL.

How to use

1. Review the information you want to receive. Some event categories require Consent item settings. See Supported Event Types.
2. Configure the webhook URL and select event types. See Prerequisites.
3. Implement the functionality to validate and process the SET received through the webhook URL by referring to Validate SET.
4. Implement the necessary actions by referring to the Recommended actions column in the Event Types table.
5. To check the specifications of the Account Status Change Webhook system, see Get metadata (Optional).
6. To test how webhooks are sent, see Test (Optional).

Set Consent items

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 permissions for [Kakao Account status change details] through DevTalk.
2. Once granted, set [Kakao Account status change details] as [Optional Consent] in [My Application] > [Kakao Login] > [Consent Items]. Refer to Prerequisites.

Supported event types

The supported event types by category are as follows. If you select the category name, you can see detailed information about the events included in each category.

OAUTH

The OAUTH category includes change event types related to the OAuth 2.0 protocol.

RISC

The RISC category includes change events that notify of suspicious activities on user accounts. Scope configuration and user consent are required.

CAEP

The CAEP category includes change events related to user account credentials. Consent configuration and user consent are required.

KAKAO

The KAKAO category includes event types defined and provided by Kakao.

SET information

The service receives a SET 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...

SET configuration

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

Header

Payload

Event

Change event details

Subject

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"
}

{
    "iss": "https://kauth.kakao.com",
    "aud": "${REST_API_KEY}",
    "sub": "${USER_ID}",
    "txm": "92a79799-3ae3-4112-8fe2-921c710daa38",
    "iat": 1674702636,
    "jti": "6a1a7a3e-b923-4eb8-886c-cbcbd1621fb0",
    "events": {
        "https://schemas.openid.net/secevent/oauth/event-type/user-linked": {
            "subject": {
                "sub": "1376016924429759243",
                "subject_type": "iss-sub",
                "iss": "https://kauth.kakao.com"
            }
        }
    }
}

Validate SET

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.

Validation success response

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

Validation failure response

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."
}

Failure response error codes

Get metadata

Basic information

You can retrieve the Account status change webhook specification.

Response

Sample

Request

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

Response

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"
}

Test

You can try sending webooks to see if webhooks work normally in [Tools] > [Webhook Test].

🅐 App: Select an app to test. 🅑 Webhook URL: Displays the webhook URL you set in Account status change webhook. If you have not set, register a webhook URL first. 🅒 Category: Select a change event category. All categories can be selected for testing. 🅓 Event type: Select a change event type to send. Note that RISC and CAEP categories typically require permissions but are available for testing. 🅔 Kakao Account: Select a team member registered with the app to send the event. The selected account must be [link] to the app to trigger events. 🅕 Parameters: For some categories, you need to set parameters. See the table below for details.

After selecting [Send], the test information appears at the bottom of the page, as shown below.

🅐 Webhook request: Full text of the test request. Host and URL are excluded in the output when the webhook URL is not set. 🅑 Security event Token: The decoded value of the SET contained in the request is in 🅐. The header and payload are output respectively. Refer to this when debugging.