메인 콘텐츠로 건너뛰기
이 가이드는 X Activity API 엔드포인트를 사용하여 이벤트를 구독하고 수신하는 방법을 설명합니다. 일반적으로 다음 3단계를 수행합니다.
  1. 필터링하려는 사용자의 사용자 ID를 확인합니다.
  2. 해당 사용자에 대해 필터링할 이벤트 유형의 구독을 생성합니다.
  3. 웹훅 또는 지속적인 HTTP 스트림 연결을 통해 이벤트를 수신합니다.

​
사용자 ID 가져오기

구독을 생성하기 전에 필터링할 계정의 사용자 ID를 알아야 합니다. 이 예시에서는 XDevelopers 핸들을 사용합니다. 사용자 ID를 조회하는 방법은 다음과 같습니다. 사용자 이름으로 사용자 ID 조회: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"
내 사용자 id 가져오기: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me
두 엔드포인트 모두 구독 필터에서 사용할 수 있는 id 필드를 포함한 사용자 정보를 반환합니다. 예제 JSON 응답은 아래에 나와 있습니다: 
{
    "data": {
        "id": "2244994945",
        "name": "Developers"
        "username": "XDevelopers"
    }
}

​
구독 생성

다음 단계는 구독을 생성하는 것입니다. 이 예시에서는 XDevelopers의 프로필 소개 업데이트를 구독합니다. 이를 위해 JSON 본문에 user_id와 event_type를 전달합니다. 이 경우 event_type은 ProfileBioUpdate입니다. X Developer의 사용자 ID인 2244994945와 선택적 태그를 전달하겠습니다: 
{
  "event_type": "ProfileBioUpdate",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopers의 프로필 소개 업데이트"
}
XAA 관련 모든 엔드포인트의 인가에는 개발자 포털에서 발급받은 베어러 토큰을 사용합니다: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "Xdevelopers의 프로필 소개 업데이트"
  }'
요청이 성공하면 구독이 생성됩니다. 
{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"ProfileBioUpdate",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "Xdevelopers의 프로필 소개 업데이트"
      "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 계정이 프로필 소개를 업데이트하면 해당 이벤트가 스트림을 통해 전달됩니다: 
{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "ProfileBioUpdate",
      "tag": "Xdevelopers의 소개 업데이트",
    "payload": {
      "before": "화성 & 자동차",
      "after": "화성, 자동차 & AI"
    }
  }
}

​
구독 관리

X Activity API는 표준 CRUD 작업을 통해 구독을 관리할 수 있는 엔드포인트를 제공합니다.

​
구독 생성

이벤트를 수신할 새 구독을 생성합니다: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "내 소개 업데이트",
    "webhook_id": "1976325569252868099"
  }'
참고:
  • tag 필드는 선택 사항입니다. 전송된 이벤트를 구분하는 데 활용할 수 있습니다.
  • webhook_id 필드도 선택 사항입니다. 웹훅 설정 방법은 webhook 문서를 참조하세요. webhook_id가 지정되면, 스트림이 열려 있는 경우 이벤트는 제공된 웹훅과 스트림 모두로 전달됩니다.
응답: 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-09T16:35:08.000Z",
    "tag": "내 소개 업데이트",
    "webhook_id": "1976325569252868099"
  }
}

​
구독 목록

앱의 활성 구독을 모두 조회합니다: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions
응답: 
{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "ProfileBioUpdate",
      "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": "ProfilePictureUpdate",
      "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": "새 태그",
    "webhook_id": "192846273860294839"
  }'
응답: 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-10T17:10:58.000Z",
    "tag": "내 새 태그",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}