메인 콘텐츠로 건너뛰기

​
필터된 스트림 웹훅 API 시작하기

v2 필터된 스트림 웹훅 API는 필터링에 사용할 규칙을 설정하는 방식에서 v2 filtered stream endpoint와 유사합니다. 차이점은 규칙과 일치하는 포스트를 전달하는 메커니즘에 있습니다.
  • v2 filtered stream endpoint의 경우, 지속적인 연결을 맺고 규칙과 일치하는 포스트를 수신해야 합니다.
  • 이 filtered stream webhook endpoint의 경우, 웹훅을 등록하면 X가 규칙과 일치하는 포스트를 웹훅으로 전달합니다.
이 가이드는 filtered stream webhooks endpoint를 사용하여 포스트를 필터링하고 수신하는 방법을 설명합니다. 전체 과정은 다음 3단계로 구성됩니다.
  1. 필터된 스트림 규칙 설정
  2. 웹훅 생성
  3. Filtered Stream 인스턴스를 웹훅에 연결하기
Filtered Stream 인스턴스를 웹훅에 연결하면 X가 규칙과 일치하는 포스트를 웹훅으로 전송합니다.

​
필터링 스트림 규칙 설정하기

필터링 스트림 규칙은 하나 이상의 연산자로 구성되며, 불리언 논리와 괄호를 사용해 결합하여 어떤 포스트를 웹훅으로 전달할지 정의합니다. 필터링 스트림 웹훅 API는 규칙을 생성하고 관리하기 위해 v2 필터링 스트림 엔드포인트와 동일한 엔드포인트 집합을 사용합니다. 필터를 어떻게 구성할 수 있는지 보여주는 자세한 가이드를 참고하세요.

​
웹훅 생성하기

외부에서 접근 가능한 HTTPS URL을 X API에 등록하여 이벤트를 수신할 웹훅을 생성합니다. 웹훅은 CRC 유효성 검사를 위한 GET 요청과 이벤트 페이로드를 위한 POST 요청을 모두 처리할 수 있어야 합니다. 웹훅 생성 및 관리를 위한 자세한 단계는 웹훅 소개 문서를 참고하세요. 참고: 이미 Account Activity API (AAA)를 위해 웹훅을 사용 중이라면, 그때 설정한 웹훅과 여기에서 필요한 웹훅은 동일합니다. 또한, 처리 용량이 충분하고 이벤트를 구분해 처리할 수 있다면, AAA에 사용 중인 동일한 웹훅 엔드포인트를 이 API에서도 그대로 사용할 수 있습니다.

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

규칙을 설정하고 웹훅을 생성한 후, 해당 웹훅을 Filtered Stream 인스턴스에 연결합니다. 이렇게 하면 조건에 일치하는 게시물 이벤트가 웹훅 URL로 전달됩니다. 다음 엔드포인트를 사용합니다: POST /2/tweets/search/webhooks/:webhook_id 스트리밍 엔드포인트 /2/tweets/search/stream 에서 사용하는 것과 동일한 쿼리 매개변수(예: expansions, fields, media 옵션)를 포함할 수 있습니다. 이를 통해 이벤트 페이로드에 포함되는 데이터를 맞춤 구성할 수 있습니다. 예시: 
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 
  } 
}
팁: 동일한 스트림에 여러 개의 webhook을 연결하여 이중화를 구성하거나 서로 다른 필드 집합을 수신할 수 있습니다. 각 연결마다 고유한 매개변수를 지정할 수 있습니다. Filtered Stream 인스턴스를 webhook에 연결하면, 아래와 같이 설정한 규칙과 일치하는 포스트를 수신하기 시작합니다. 
{
    "data": {
        "id": "1346889436626259968",
        "text": "Learn how to use the user Post timeline and user mention timeline endpoints in the X API v2 to explore Post… 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"
        }
    ]
}

​
Filtered Stream에 연결된 웹훅 가져오기

현재 Filtered Stream에 연결된 모든 웹훅 목록을 가져옵니다: 
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
    }
}