스트리밍 이벤트를 위한 X Activity API 빠른 시작 가이드

이 가이드는 X Activity API 엔드포인트를 사용하여 이벤트를 구독하고 수신하는 방법을 설명합니다. 일반적으로 다음 세 가지 단계로 이루어집니다:

이벤트를 필터링할 대상 User의 User ID를 식별합니다
해당 User에 대해 필터링하려는 이벤트 유형에 대한 구독을 생성합니다
웹훅 또는 지속적인 HTTP 스트림 연결을 통해 이벤트를 수신합니다

사전 요구 사항시작하기 전에 다음이 필요합니다:

승인된 App이 있는 개발자 계정
App의 Bearer Token

user ID 가져오기

구독을 생성하기 전에 필터링할 계정의 user ID를 알아야 합니다. 이 예제에서는 XDevelopers 핸들을 사용합니다. 다음과 같은 여러 가지 방법으로 user ID를 조회할 수 있습니다: username으로 user의 ID 조회:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"

본인의 user ID 가져오기:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me

두 엔드포인트 모두 id 필드를 포함한 user 정보를 반환하며, 이를 구독 필터에 사용할 수 있습니다. 예시 JSON 응답은 다음과 같습니다:

{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}

구독 생성

다음 단계는 구독을 생성하는 것입니다. 이 예제에서는 XDevelopers의 프로필 소개(bio) 업데이트를 구독합니다. 이를 위해 JSON 본문에 user_id와 event_type을 전달합니다. 여기서 event_type은 profile.update.bio입니다. X Developer의 user ID 2244994945와 선택적인 태그를 전달합니다:

{
  "event_type": "profile.update.bio",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopers' bio updates"
}

인증을 위해 (개발자 포털의) bearer token을 사용합니다. 이와 같은 공개 이벤트에는 app-only bearer token이 사용 가능합니다. 일부 이벤트는 비공개이며 user-context (OAuth 2.0) 인증을 필요로 합니다 — 자세한 내용은 이벤트 프라이버시 및 인증을 참조하세요.

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

요청이 성공하면 구독이 생성됩니다:

profile.update.bio

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

이벤트 수신하기

구독을 생성한 후에는 웹훅 또는 지속적인 HTTP 스트림을 통해 이벤트를 수신할 수 있습니다. 이 예제에서는 지속적인 HTTP 스트림을 엽니다:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/activity/stream

Xdevelopers 계정이 프로필 bio를 업데이트하면 해당 이벤트가 스트림을 통해 전달됩니다:

profile.update.bio

{
  "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 작업을 통해 구독을 관리할 수 있는 엔드포인트를 제공합니다.

구독 생성

이벤트를 수신하기 위해 새로운 구독을 생성합니다:

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 필드도 선택 사항입니다. 웹훅 설정에 대한 도움말은 웹훅 문서를 참조하세요. webhook_id가 지정되면 스트림이 열려 있는 경우 스트림뿐만 아니라 지정된 웹훅으로도 이벤트가 전달됩니다.

응답:

profile.update.bio

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

구독 목록

애플리케이션의 활성 구독을 모두 조회합니다:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions

응답:

profile.update.bio

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

구독 삭제

구독을 제거합니다:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096

응답:

{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}

total_subscriptions는 삭제 작업 후 앱에 남아있는 구독의 수를 나타냅니다.

구독 업데이트

PUT 엔드포인트를 사용하면 구독의 전달 방법이나 태그를 업데이트할 수 있습니다. filter 또는 event_type을 업데이트하려면 기존 구독을 삭제하고 새 구독을 추가해야 합니다.

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

응답:

profile.update.bio

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

API 참조

전체 엔드포인트 문서

웹훅

웹훅 전달 설정

Getting Started

Products

Fundamentals

Partners & Customers

Resources

스트리밍 이벤트를 위한 X Activity API 빠른 시작 가이드

user ID 가져오기

구독 생성

이벤트 수신하기

구독 관리

구독 생성

구독 목록

구독 삭제

구독 업데이트

다음 단계

이벤트 페이로드

API 참조

웹훅

​user ID 가져오기

​구독 생성

​이벤트 수신하기

​구독 관리

​구독 생성

​구독 목록

​구독 삭제

​구독 업데이트

​다음 단계

이벤트 페이로드

API 참조

웹훅

user ID 가져오기

구독 생성

이벤트 수신하기

구독 관리

구독 생성

구독 목록

구독 삭제

구독 업데이트

다음 단계