Configurar notificações usando webhooks

Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

O que é um webhook?

Um webhook define um gerenciador de callback HTTP acionado por um evento. É possível criar webhooks e configurá-los para processar notificações de eventos, como uma alternativa aos modelos de notificação de monetização, conforme descrito em Configurar notificações usando modelos de notificação.

Para configurar notificações usando webhooks, siga as etapas abaixo usando a interface do Edge Management ou a API Management and Monetization:

  1. Adicione webhooks que definem os manipuladores de callback para os eventos de notificação usando a interface ou a API.
  2. Configure o gerenciador de callback.
  3. Configure a notificação para um plano de taxa ajustável usando a interface ou a API.

Gerenciar webhooks

Adicionar e gerenciar webhooks que definem os manipuladores de callback para os eventos de notificação usando a interface ou a API.

Como gerenciar webhooks usando a IU

Adicione e gerencie webhooks que definem os manipuladores de callback para os eventos de notificação usando a interface, conforme descrito nas seções a seguir.

Como usar a página "Webhooks"

Acesse a página "Webhooks", conforme descrito abaixo.

Edge

Para acessar a página "Webhooks" usando a interface do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Publicar > Monetização > Webhooks na barra de navegação à esquerda.

A página "Webhooks" é exibida.

Conforme destacado na figura, a página "Webhooks" permite:

Edge clássico (nuvem privada)

Para acessar a página "Webhooks" usando a IU clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.

  2. Selecione Administrador > Webhooks.

A página "Webhooks" será exibida.

Na página "Webhooks", é possível:

Como adicionar um webhook usando a interface

Para adicionar um webhook usando a interface:

  1. Acesse a página "Webhooks".
  2. Clique em + Webhook.
  3. Insira as seguintes informações (todos os campos são obrigatórios).
    Campo Descrição
    Nome Nome do webhook.
    URL URL do gerenciador de callback que será chamado quando a notificação de evento for acionada. Consulte Como configurar o gerenciador de callback.
  4. Clique em Salvar.

O webhook é adicionado à lista e ativado por padrão.

Como editar um webhook na interface

Para editar um webhook usando a interface:

  1. Acesse a página "Webhooks".
  2. Posicione o cursor sobre o webhook que você quer editar e clique em no menu de ações.
  3. Edite os campos do webhook, conforme necessário.
  4. Clique em Atualizar webhook.

Como ativar ou desativar um webhook usando a interface

Para ativar ou desativar um webhook usando a interface:

  1. Acesse a página "Webhooks".
  2. Posicione o cursor sobre o webhook e ative ou desative a chave de status.

Como excluir um webhook usando a interface

Para excluir um webhook usando a interface:

  1. Acesse a página "Webhooks".
  2. Posicione o cursor sobre o webhook que você quer excluir e clique em .

O webhook é excluído e removido da lista.

Como gerenciar webhooks usando a API

Adicione e gerencie webhooks usando a API, conforme descrito nas seções a seguir.

Como visualizar todos os webhooks usando a API

Confira todos os webhooks emitindo uma solicitação GET para /mint/organizations/{org_name}/webhooks. Exemplo:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

Confira a seguir um exemplo da resposta retornada:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

Como visualizar um webhook usando a API

Para conferir um único webhook, emita uma solicitação GET para /mint/organizations/{org_name}/webhooks/{webhook_id}.

Exemplo:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Veja a seguir um exemplo de resposta:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

Como adicionar um webhook usando a API

Adicione um webhook emitindo uma solicitação POST para /mint/organizations/{org_name}/webhooks. Transmita o nome do webhook e o URL do gerenciador de callback que será chamado quando a notificação de eventos for acionada.

Por exemplo, o código a seguir cria um webhook chamado webhook3 e atribui callbackhandler3 a ele:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

Veja a seguir um exemplo de resposta:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Como editar um webhook usando a API

Edite um webhook emitindo uma solicitação PUT para /mint/organizations/{org_name}/webhooks/{webhook_id}. Transmita as atualizações no corpo da solicitação.

Por exemplo, o código a seguir atualiza o gerenciador de callback associado a webhook1:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

Veja a seguir um exemplo de resposta:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Como ativar ou desativar um webhook usando a API

Ative ou desative um webhook emitindo uma solicitação POST para /mint/organizations/{org_name}/webhooks/{webhook_id}, como você fez ao atualizar um webhook, e defina o atributo ativado no corpo da solicitação como verdadeiro ou falso, respectivamente. Se você desativar o webhook, ele não será acionado quando um evento ocorrer.

Por exemplo, o comando a seguir ativa webhook3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

Veja a seguir um exemplo de resposta:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Como excluir um webhook usando a API

Exclua um webhook emitindo uma solicitação DELETE para /mint/organizations/{org_name}/webhooks/{webhook_id}.

Para especificar se a exclusão do webhook será forçada se houver processos em andamento, defina o parâmetro de consulta forceDelete como true ou false. O parâmetro de consulta forceDelete é ativado (true) por padrão.

Por exemplo, o seguinte comando exclui webhook3:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Configurar o gerenciador de callback

Veja a seguir o formato da solicitação JSON que é enviada ao gerenciador de callback definido por um webhook quando uma notificação de evento é acionada. É necessário garantir que o gerenciador de callback processe a solicitação adequadamente.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

Como configurar notificações para um plano de taxa ajustável

Configure notificações usando webhooks para um plano de taxa ajustável usando a interface ou a API.

Configurar notificações para um plano de taxas ajustável usando a interface

Configure as notificações usando webhooks para um plano de taxas ajustável usando a interface, conforme descrito abaixo.

Acessar a caixa de diálogo "Notificações" de um plano de tarifa ajustável

Acesse a caixa de diálogo "Notificações" para conferir um plano de tarifas ajustável, conforme descrito abaixo.

Edge

Para acessar a caixa de diálogo de notificações usando a interface do Edge:

  1. Crie e publique um plano de taxa de notificação ajustável, conforme descrito em Especificar detalhes do plano de notificação ajustável.
  2. Acesse a página "Planos de taxas" selecionando Publicar > Monetização > Planos de taxas na barra de navegação à esquerda.
  3. Posicione o cursor sobre o plano de taxa de notificação ajustável publicado para mostrar as ações.
  4. Clique em +Notificar.

    A caixa de diálogo "Notificações" é exibida.

    Observação: o plano de taxas precisa ser publicado para que a ação +Notificar seja exibida.

Edge clássico (nuvem privada)

Para acessar a página "Notificações":

  1. Crie um plano de taxa de notificação ajustável, conforme descrito em Especificar detalhes do plano de notificação ajustável.
  2. Selecione Publicar > Pacotes para conferir os planos de taxas.
  3. Clique em +Notificar na coluna "Ações" do plano de tarifas.

    A caixa de diálogo "Notificações" é exibida.

Como adicionar notificações para um plano de taxas ajustável usando a interface

Para adicionar notificações de um plano de taxas ajustável na interface:

  1. Acesse a caixa de diálogo Notificações.
  2. Em Intervalos de notificação, defina a condição de notificação especificando uma porcentagem do número desejado de transações em que você quer que uma notificação seja acionada. Em especial:
    • Para definir uma porcentagem exata, digite a porcentagem no campo At/From % e deixe o campo To % em branco.
    • Para definir um intervalo de porcentagem, insira as porcentagens inicial e final nos campos At/From % e To %, respectivamente, e um valor de incremento no campo Step %. Por padrão, as notificações são enviadas em incrementos de 10% dentro do intervalo especificado.

    O campo Notify At é atualizado para refletir cada porcentagem do número de transações desejado que vai acionar um evento.

  3. Para definir outras condições de notificação, clique em +Adicionar e repita a etapa 4.
  4. Defina a ação de notificação em Webhooks selecionando um ou mais webhooks para gerenciar o processamento de callback quando as notificações forem acionadas.
  5. Clique em Criar notificação.

Como editar notificações de um plano de taxas ajustável usando a interface

Para editar as notificações de um plano de taxas ajustável na IU:

  1. Acesse a caixa de diálogo de notificações.
  2. Clique em +Notificar na coluna "Ações" do plano de preços.
  3. Clique em Editar.
  4. Modifique os valores conforme necessário.
  5. Clique em Salvar notificação.

Como excluir notificações de um plano de taxas ajustável usando a interface

Para excluir uma condição e uma ação de notificação:

  1. Acesse a caixa de diálogo Notificações.
  2. Clique em +Notificar na coluna "Ações" do plano de preços.
  3. Clique em Excluir notificação.

Configurar notificações para um plano de tarifas ajustável usando a API

Para configurar uma notificação para um plano de taxas ajustável usando a API, use o procedimento descrito em Como gerenciar condições e ações de notificação usando a API e use os atributos descritos nesta seção.

Para configurar a condição de notificação (notificationCondition), use os valores de atributo a seguir. Para mais informações, consulte Propriedades de configuração para condições de notificação.

Atributo Valor
RATEPLAN ID do plano de tarifação de notificação ajustável.
PUBLISHED TRUE para indicar que o plano de tarifas de notificação ajustável precisa ser publicado.
UsageTarget Porcentagem do número de transações desejado em que uma notificação será acionada.

Esse atributo permite notificar os desenvolvedores quando eles estão se aproximando ou atingiram o número desejado de transações para um plano de tabela de preços de notificação ajustável que eles compraram. Por exemplo, se um desenvolvedor comprou um plano de taxa de notificação ajustável e o número desejado de transações foi definido como 1.000, você pode notificá-lo quando ele atingir 800 transações (80% do número desejado de transações), 1.000 transações (100%) ou 1.500 transações (150%).

  • Para definir uma porcentagem exata, digite %= n. Por exemplo, %= 80 vai enviar notificações quando a porcentagem do número desejado de transações atingir 80%.
  • Para definir um intervalo de porcentagem, insira as porcentagens inicial e final e o valor pelo qual incrementar da seguinte maneira: %= start to end by n. Por exemplo, um valor de %= 80 to 100 by 10 vai enviar notificações quando a porcentagem do número de transações desejado chegar a 80%, 90% e 100%.

Para configurar a ação de notificação, em actions, defina os seguintes valores. Para mais informações, consulte Propriedades de configuração para ações de notificação.

Atributo Valor
actionAttribute WEBHOOK para acionar um webhook.
value ID do webhook que você definiu na seção anterior, Criar webhooks usando a API.

Confira a seguir um exemplo de como criar uma condição de notificação que aciona um webhook quando a porcentagem do número de destino de transações atingir 80%, 90%, 100%, 110% e 120%.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

Para saber como visualizar, atualizar e excluir uma condição e uma ação de notificação, consulte:

Códigos de resposta do webhook

Confira a seguir um resumo dos códigos de resposta do webhook e como eles são interpretados pelo sistema.

Código de resposta Descrição
2xx Sucesso
5xx

Falha na solicitação. O sistema vai tentar a solicitação até três vezes em intervalos de 5 minutos.

Observação : os limites de tempo de leitura e conexão para solicitações de webhook são de 3 segundos cada, o que pode resultar em falhas.
Other response Falha na solicitação. O sistema não vai repetir a solicitação.