This document guides the webhook information for the Kakao Developers.

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

The Kakao Developers supports the following webhooks.

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.

• 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.

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

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.

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.

• 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.

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.

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.

• 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.

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