Pular para o conteúdo principal

​
Introdução à API de webhooks do stream filtrado

A API de webhooks do stream filtrado v2 é semelhante ao endpoint de stream filtrado v2 no que diz respeito à configuração das regras de filtragem. A diferença está no mecanismo de entrega dos Posts que correspondem às suas regras.
  • No caso do endpoint de stream filtrado v2, você precisa estabelecer uma conexão persistente e ficar escutando os Posts que corresponderem às suas regras.
  • No caso deste endpoint de webhook do stream filtrado, você registra seu webhook e o X entrega os Posts que corresponderem às suas regras ao seu webhook.
Este guia explica como filtrar e receber Posts usando os endpoints de webhooks do stream filtrado. Há 3 etapas envolvidas:
  1. Configurar suas regras do stream filtrado
  2. Criar seu webhook
  3. Vincular sua instância do Filtered Stream ao seu webhook
Depois de vincular sua instância do Filtered Stream ao seu webhook, o X enviará os Posts que corresponderem às suas regras para seus webhooks.

​
Configurando suas regras do stream filtrado

As regras do stream filtrado são compostas por um ou mais operadores, combinados com lógica booleana e parênteses, para definir quais Posts serão entregues aos seus webhooks. A API de webhooks do stream filtrado usa o mesmo conjunto de endpoints do endpoint v2 do stream filtrado para criar e gerenciar regras. Confira este guia detalhado que mostra como você pode construir filtros.

​
Criando seu webhook

Crie um webhook para receber eventos registrando uma URL HTTPS publicamente acessível na X API. Os webhooks devem atender a solicitações GET para validação CRC e a solicitações POST para cargas (payloads) de eventos. Siga a documentação de introdução a webhooks para etapas detalhadas sobre como criar e gerenciar webhooks. Observação: Se você já usa webhooks para a Account Activity API (AAA), os webhooks configurados lá funcionam exatamente da mesma forma aqui. Na prática, você pode reutilizar o mesmo endpoint de webhook que usa para a AAA nesta API, desde que tenha capacidade e consiga separar os eventos.

​
Vinculando sua instância do stream filtrado ao seu webhook

Depois que suas regras estiverem definidas e o webhook for criado, vincule o webhook à sua instância do stream filtrado. Isso encaminha eventos de Post correspondentes para a URL do seu webhook. Use o endpoint: POST /2/tweets/search/webhooks/:webhook_id Você pode incluir parâmetros de query idênticos aos usados no endpoint de stream /2/tweets/search/stream, como expansions, fields e opções de mídia. Isso personaliza os data incluídos nos payloads de evento. Exemplo: 
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'
Exemplo de resposta bem-sucedida: 
{ 
  "data": { 
    "provisioned": true
  } 
}
Dica: Você pode vincular vários webhooks ao mesmo stream para redundância ou para receber conjuntos de campos diferentes. Cada vinculação pode especificar parâmetros exclusivos. Depois que você tiver sua instância do Filtered Stream vinculada ao seu webhook, você começará a receber Posts que correspondam às suas regras, como mostrado abaixo: 
{
    "data": {
        "id": "1346889436626259968",
        "text": "Aprenda como usar os endpoints de timeline de Posts do usuário e timeline de menções do usuário na X API v2 para explorar Posts… https://t.co/56a0vZUx7i",
        "created_at": "2021-01-06T18:40:40.000Z",
        "author_id": "2244994945"
    },
    "includes": {
        "users": [
            {
                "id": "2244994945",
                "name": "Desenvolvedores",
                "username": "Xdevelopers",
                "created_at": "2013-12-14T04:35:55Z",
                "protected": false
            }
        ]
    },
    "matching_rules": [
        {
            "id": "120897978112909812",
            "tag": "api-posts"
        }
    ]
}

​
Recuperando webhooks vinculados ao stream filtrado

Recupere a lista de todos os webhooks atualmente vinculados ao seu stream filtrado: 
GET /2/tweets/search/stream/webhooks
Exemplo de resposta: 
{
    "data": {
        "links": [
            {
                "application_id": "29893711",
                "business_user_id": "1877374016438091776",
                "fields": [
                    "user.fields=username",
                    "name",
                    "id",
                    "expansions=author_id"
                ],
                "instance_id": "1877375130462289920",
                "webhook_id": "1952390923729424384"
            }
        ]
    }
}

​
Desvincular seu webhook do stream filtrado

Para deixar de receber eventos em um webhook específico, desvincule-o usando: 
DELETE /2/tweets/search/webhooks/:webhook_id
A resposta será a seguinte: 
{
    "data": {
        "deleted": true
    }
}
⌘I