Webhook

This document guides the webhook information for the Kakao API platform.

Overview

Webhooks let the Kakao API Platform quickly notify your service of user activities or account status changes by sending HTTP requests.

The Kakao API Platform supports the following webhooks.

Webhook	Description	Related product
Unlink webhook	Sends a webhook when a user unlinks their Kakao Account from a service app.	Kakao Login
Account status change webhook	Sends a webhook when a user's Kakao Account status changes.	Kakao Login
Kakao Talk Share webhook	Sends a webhook when a Kakao Talk Share message is successfully sent to the selected users or chatrooms.	Kakao Talk Share
Kakao Talk Channel webhook	Sends a webhook when a user adds or blocks one of your Kakao Talk Channels.	Kakao Talk Channel

Implementation steps

To implement webhooks in your service, follow these steps.

1. Implement a webhook receiver

To receive webhooks from Kakao, you must build an API endpoint. You need to do as below.

• Build an endpoint that handles the webhook requests that Kakao sends with a POST or GET method.
  • (Example: https://{SERVICE_DOMAIN}/webhook)
• Parse the event data sent in JSON format or as URL query parameters.
• Use the domain with a valid SSL certificate because webhook requests are sent via HTTPS protocol.

If you manage an ACL (Access Control List), see IP allowlist for webhooks.

2. Configure in Kakao Developers

Register the endpoint you created as a webhook URL in Kakao Developers.

• Set unlink webhook
• Set account status change webhook
• Set Kakao Talk Share webhook
• Set Kakao Talk Channel webhook

3. Handle webhook requests

When an event triggers, Kakao sends an HTTP request to your endpoint.

Your service that receives the request must handle as below.

1. Parse the request body payload to identify the event.
2. Perform any follow-up actions based on the event, such as deactivating a user or updating account status.
3. Return the appropriate HTTP status code within 3 seconds, such as 200 OK or 202 Accepted. Kakao checks only the status code, not the response body.

Required actions

Webhook	Actions
Unlink webhook	1. Verify the webhook with the admin key and app_id. 2. If valid, update the database of the user by deactivating, deleting, and so on according to Privacy policies and Terms of Service.
Account status change webhook	1. Decode and verify the SET token (Security Event Token). 2. Implement the recommended actions for each event type by referring to Recommended actions in the tables.
Kakao Talk Share webhook	Perform any internal processing based on serverCallbackArgs (optional).
Kakao Talk Channel webhook	Update the added or blocked status of Kakao Talk Channel.

4. Test webhooks

After you implement webhooks, use the Kakao webhook testing tool to send test events and verify your handling. See Webhook test.

Usage policy

Required response format

You must respond to every webhook request within 3 seconds with the correct HTTP status code (Example: 200 OK, 202 Accepted).

For the Required response format, see each webhook’s documentation.

• Unlink webhook
• Account status change webhook
• Kakao Talk Share webhook
• Kakao Talk Channel webhook

You do not need to include a response body, as Kakao determines success solely based on the HTTP status code.

Webhook deactivation

A webhook may be deactivated if there is no response for over one month under the required response format or if a high error rate persists.

• If the Unlink webhook is deactivated, email and web notifications are sent to your team members. After resolving any issues, re-enable the webhook by referring to Set unlink webhook.
• If the Account status change webhook fails continuously for over 3 hours, the webhook is deactivated. You can re-enable the webhook by referring to Set Account status change webhook.

IP allowlist for webhooks

If your service manages an ACL (Access Control List) on the server, add Kakao's IP addresses to the allowlist so it can receive webhook requests. See Firewall.

Webhook retry

If your server fails to handle a webhook, Kakao redelivers the event so that your service can process the missing event.

This feature is only available for Account status change webhook.

Retry interval

If your server does not respond to the initial request, Kakao retries step by step as below.

• Stage 1: Resend twice at 5-minute intervals.
• Stage 2: Resend twice at 30-minute intervals.
• Stage 3: Resend once after 60 minutes.

If none of the six attempts succeeds, Kakao considers the webhook delivery as failed.

In addition, if failures continue for 3 hours, Kakao deactivates the webhook immediately, regardless of the remaining retries.

Reactivation

To start receiving requests again, re-enable the webhook on the Account status change webhook page.