메인 콘텐츠로 건너뛰기

​
filtered stream webhooks API 시작하기

v2 filtered stream webhooks API는 필터링 규칙을 설정하는 측면에서 v2 filtered stream 엔드포인트와 유사합니다. 차이점은 규칙과 일치하는 게시물을 전달하는 방식에 있습니다.
  • v2 filtered stream 엔드포인트의 경우, 지속적인 연결을 유지하며 규칙과 일치하는 게시물을 수신해야 합니다.
  • 이 filtered stream webhook 엔드포인트의 경우, webhook을 등록하면 X가 규칙과 일치하는 게시물을 해당 webhook으로 전달합니다.
이 가이드는 filtered stream webhooks 엔드포인트를 사용해 게시물을 필터링하고 수신하는 방법을 설명합니다. 총 3단계가 포함됩니다.
  1. filtered stream 규칙 설정
  2. webhook 생성
  3. Filtered Stream 인스턴스를 webhook에 연결
Filtered Stream 인스턴스를 webhook에 연결하면 X가 규칙과 일치하는 게시물을 webhook으로 전송합니다.

​
필터된 스트림 규칙 설정

필터된 스트림 규칙은 하나 이상의 연산자를 불리언 논리와 괄호로 조합해 어떤 게시물이 웹훅으로 전달될지 정의하도록 구성됩니다. 필터된 스트림 웹훅 API는 규칙을 생성하고 관리하기 위해 v2 필터된 스트림 엔드포인트와 동일한 엔드포인트 집합을 사용합니다. 필터를 구축하는 방법을 보여 주는 자세한 가이드를 확인하세요.

​
웹훅 생성

X API에 공개적으로 접근 가능한 HTTPS URL을 등록하여 이벤트를 수신할 웹훅을 만듭니다. 웹훅은 CRC 검증을 위한 GET 요청과 이벤트 페이로드를 위한 POST 요청을 처리해야 합니다. 웹훅 생성 및 관리에 대한 자세한 절차는 Webhooks Introduction documentation을 참고하세요. 참고: 이미 Account Activity API(AAA)용 웹훅을 사용 중이라면, 해당 웹훅 설정은 여기서도 동일합니다. 실제로, 처리 여유가 있고 이벤트를 구분해 처리할 수 있다면 AAA에서 사용 중인 동일한 웹훅 엔드포인트를 이 API에도 사용할 수 있습니다.

​
Filtered Stream 인스턴스를 웹훅에 연결하기

규칙을 설정하고 웹훅을 생성했으면, 웹훅을 Filtered Stream 인스턴스에 연결하세요. 이렇게 하면 일치하는 게시물 이벤트가 웹훅 URL로 전달됩니다. 사용할 엔드포인트: POST /2/tweets/search/webhooks/:webhook_id 스트리밍 엔드포인트 /2/tweets/search/stream에서 사용하는 것과 동일한 쿼리 매개변수(예: expansions, 필드, 미디어 옵션)를 포함할 수 있습니다. 이를 통해 이벤트 페이로드에 포함될 데이터를 맞춤화할 수 있습니다. 예시: 
curl --request POST \ 
  --url 
'https://api.x.com/2/tweets/search/webhooks/123456789012345678?ex
pansions=author_id&user.fields=username,name,id' \ 
  --header 'Authorization: Bearer $BEARER_TOKEN'
성공한 응답 예시: 
{ 
  "data": { 
    "provisioned": true
  } 
}
팁: 중복 대비나 서로 다른 필드 세트를 받기 위해 동일한 스트림에 여러 웹훅을 연결할 수 있습니다. 각 연결마다 고유한 매개변수를 지정할 수 있습니다. Filtered Stream 인스턴스를 웹훅에 연결하면 아래와 같이 규칙에 맞는 게시물을 받기 시작합니다: 
{
    "data": {
        "id": "1346889436626259968",
        "text": "X API v2에서 사용자 게시물 타임라인과 사용자 멘션 타임라인 엔드포인트를 사용하는 방법을 알아보고 게시물을 탐색해 보세요… https://t.co/56a0vZUx7i",
        "created_at": "2021-01-06T18:40:40.000Z",
        "author_id": "2244994945"
    },
    "includes": {
        "users": [
            {
                "id": "2244994945",
                "name": "Developers",
                "username": "Xdevelopers",
                "created_at": "2013-12-14T04:35:55Z",
                "protected": false
            }
        ]
    },
    "matching_rules": [
        {
            "id": "120897978112909812",
            "tag": "api-posts"
        }
    ]
}

​
필터된 스트림에 연결된 웹후크 조회

현재 필터된 스트림에 연결된 모든 웹후크 목록을 조회합니다: 
GET /2/tweets/search/stream/webhooks
예시 응답: 
{
    "data": {
        "links": [
            {
                "application_id": "29893711",
                "business_user_id": "1877374016438091776",
                "fields": [
                    "user.fields=username",
                    "name",
                    "id",
                    "expansions=author_id"
                ],
                "instance_id": "1877375130462289920",
                "webhook_id": "1952390923729424384"
            }
        ]
    }
}

​
Filtered Stream에서 웹훅 연결 해제

특정 웹훅의 이벤트 수신을 중지하려면 다음 명령으로 연결을 해제하세요: 
DELETE /2/tweets/search/webhooks/:webhook_id
응답은 다음과 같습니다. 
{
    "data": {
        "deleted": true
    }
}