> ## Documentation Index > Fetch the complete documentation index at: https://docs.x.com/llms.txt > Use this file to discover all available pages before exploring further. # 스트리밍 이벤트를 위한 X Activity API 빠른 시작 가이드 > 이 가이드는 X Activity API 엔드포인트를 사용하여 이벤트를 구독하고 수신하는 방법을 설명합니다. activity를 다루는 X API v2 표준 계층에 대한 참고 자료입니다. export const Button = ({href, children}) => { return
; }; 이 가이드는 X Activity API 엔드포인트를 사용하여 이벤트를 구독하고 수신하는 방법을 설명합니다. 일반적으로 다음 세 가지 단계로 이루어집니다: 1. 이벤트를 필터링할 대상 User의 User ID를 식별합니다 2. 해당 User에 대해 필터링하려는 이벤트 유형에 대한 구독을 생성합니다 3. 웹훅 또는 지속적인 HTTP 스트림 연결을 통해 이벤트를 수신합니다 **사전 요구 사항** 시작하기 전에 다음이 필요합니다: * 승인된 App이 있는 [개발자 계정](https://developer.x.com/en/portal/petition/essential/basic-info) * App의 [Bearer Token](/resources/fundamentals/authentication) *** ## user ID 가져오기 구독을 생성하기 전에 필터링할 계정의 user ID를 알아야 합니다. 이 예제에서는 XDevelopers 핸들을 사용합니다. 다음과 같은 여러 가지 방법으로 user ID를 조회할 수 있습니다: **username으로 user의 ID 조회:** ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers" ``` **본인의 user ID 가져오기:** ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me ``` 두 엔드포인트 모두 `id` 필드를 포함한 user 정보를 반환하며, 이를 구독 필터에 사용할 수 있습니다. 예시 JSON 응답은 다음과 같습니다: ```json theme={null} { "data": { "id": "2244994945", "name": "Developers", "username": "XDevelopers" } } ``` *** ## 구독 생성 다음 단계는 구독을 생성하는 것입니다. 이 예제에서는 XDevelopers의 프로필 소개(bio) 업데이트를 구독합니다. 이를 위해 JSON 본문에 `user_id`와 `event_type`을 전달합니다. 여기서 `event_type`은 `profile.update.bio`입니다. X Developer의 user ID `2244994945`와 선택적인 태그를 전달합니다: ```json theme={null} { "event_type": "profile.update.bio", "filter": { "user_id": "2244994945" }, "tag": "Xdevelopers' bio updates" } ``` 인증을 위해 (개발자 포털의) [bearer token](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#bearer-token-also-known-as-app-only)을 사용합니다. 이와 같은 공개 이벤트에는 app-only bearer token이 사용 가능합니다. 일부 이벤트는 비공개이며 [user-context (OAuth 2.0)](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#oauth-2-0-authorization-code-flow-with-pkce) 인증을 필요로 합니다 — 자세한 내용은 [이벤트 프라이버시 및 인증](/x-api/activity/introduction#event-privacy-and-authentication)을 참조하세요. ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ https://api.x.com/2/activity/subscriptions \ -X POST \ -d '{ "event_type": "profile.update.bio", "filter": { "user_id": "2244994945" }, "tag": "Xdevelopers' bio updates" }' ``` 요청이 성공하면 구독이 생성됩니다: ```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null} { "data":[ { "created_at":"2025-10-09T16:35:08.000Z", "event_type":"profile.update.bio", "filter":{ "user_id":"2244994945" }, "subscription_id":"1976325569252868096", "tag": "Xdevelopers' bio updates", "updated_at":"2025-10-09T16:35:08.000Z" } ], "meta": { "total_subscriptions": 1 } } ``` *** ## 이벤트 수신하기 구독을 생성한 후에는 [웹훅](https://docs.x.com/x-api/webhooks/introduction) 또는 지속적인 HTTP 스트림을 통해 이벤트를 수신할 수 있습니다. 이 예제에서는 지속적인 HTTP 스트림을 엽니다: ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/activity/stream ``` Xdevelopers 계정이 프로필 bio를 업데이트하면 해당 이벤트가 스트림을 통해 전달됩니다: ```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null} { "data": { "filter": { "user_id": "2244994945" }, "event_type": "profile.update.bio", "tag": "Xdevelopers' bio updates", "payload": { "before": "Mars & Cars", "after": "Mars, Cars & AI" } } } ``` *** ## 구독 관리 X Activity API는 표준 CRUD 작업을 통해 구독을 관리할 수 있는 엔드포인트를 제공합니다. ### 구독 생성 이벤트를 수신하기 위해 새로운 구독을 생성합니다: ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -X POST \ https://api.x.com/2/activity/subscriptions \ -d '{ "event_type": "profile.update.bio", "filter": { "user_id": "123456789" }, "tag": "my bio updates", "webhook_id": "1976325569252868099" }' ``` * `tag` 필드는 선택 사항입니다. 이벤트 전달 시 식별에 도움이 될 수 있습니다. * `webhook_id` 필드도 선택 사항입니다. 웹훅 설정에 대한 도움말은 [웹훅 문서](https://docs.x.com/x-api/webhooks/introduction)를 참조하세요. `webhook_id`가 지정되면 스트림이 열려 있는 경우 스트림뿐만 아니라 지정된 웹훅으로도 이벤트가 전달됩니다. **응답:** ```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null} { "data": { "subscription_id": "1976325569252868096", "event_type": "profile.update.bio", "filter": { "user_id": "123456789" }, "created_at": "2025-10-09T16:35:08.000Z", "updated_at": "2025-10-09T16:35:08.000Z", "tag": "my bio updates", "webhook_id": "1976325569252868099" } } ``` ### 구독 목록 애플리케이션의 활성 구독을 모두 조회합니다: ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ https://api.x.com/2/activity/subscriptions ``` **응답:** ```json title="profile.update.bio" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null} { "data": [ { "subscription_id": "1976325569252868096", "event_type": "profile.update.bio", "filter": { "user_id": "123456789" }, "created_at": "2025-10-09T16:35:08.000Z", "updated_at": "2025-10-10T03:50:59.000Z" }, { "subscription_id": "1976325569252868097", "event_type": "profile.update.profile_picture", "filter": { "user_id": "987654321" }, "created_at": "2025-10-08T14:35:08.000Z", "updated_at": "2025-10-08T14:35:08.000Z" } ], "meta": { "total_subscriptions": 2 } } ``` ### 구독 삭제 구독을 제거합니다: ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -X DELETE \ https://api.x.com/2/activity/subscriptions/1976325569252868096 ``` **응답:** ```json theme={null} { "data": { "deleted": true }, "meta": { "total_subscriptions": 0 } } ``` `total_subscriptions`는 삭제 작업 후 앱에 남아있는 구독의 수를 나타냅니다. ### 구독 업데이트 PUT 엔드포인트를 사용하면 구독의 전달 방법이나 태그를 업데이트할 수 있습니다. `filter` 또는 `event_type`을 업데이트하려면 기존 구독을 삭제하고 새 구독을 추가해야 합니다. ```bash theme={null} curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \ -X PUT \ https://api.x.com/2/activity/subscriptions/1976325569252868096 \ -d '{ "tag": "my new tag", "webhook_id": "192846273860294839" }' ``` **응답:** ```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null} { "data": { "subscription_id": "1976325569252868096", "event_type": "profile.update.bio", "filter": { "user_id": "123456789" }, "created_at": "2025-10-09T16:35:08.000Z", "updated_at": "2025-10-10T17:10:58.000Z", "tag": "my new tag", "webhook_id": "192846273860294839" }, "meta": { "total_subscriptions": 1 } } ``` *** ## 다음 단계 각 activity 이벤트 유형에 대한 샘플 JSON 전체 엔드포인트 문서 웹훅 전달 설정