This document guides the webhook information for the Kakao API platform.
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 |
To implement webhooks in your service, follow these steps.
To receive webhooks from Kakao, you must build an API endpoint. You need to do as below.
https://{SERVICE_DOMAIN}/webhook
)If you manage an ACL (Access Control List), see IP allowlist for webhooks.
Register the endpoint you created as a webhook URL in Kakao Developers.
When an event triggers, Kakao sends an HTTP request to your endpoint.
Your service that receives the request must handle as below.
200 OK
or 202 Accepted
. Kakao checks only the status code, not the response body.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. |
After you implement webhooks, use the Kakao webhook testing tool to send test events and verify your handling. See Webhook test.
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.
You do not need to include a response body, as Kakao determines success solely based on the HTTP status code.
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 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.
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.
If your server does not respond to the initial request, Kakao retries step by step as below.
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.
To start receiving requests again, re-enable the webhook on the Account status change webhook page.