Configurar notificações usando webhooks

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O que é um webhook?

Um webhook define um gerenciador de callback HTTP acionado por um evento. Você pode criar webhooks e configurá-los para processar notificações de eventos, como alternativa ao uso do modelos de notificação sobre monetização, conforme descrito em Configurar notificações usando modelos de notificação.

Para configurar notificações usando webhooks, conclua as etapas a seguir usando o Edge Management interface do usuário ou API Management and Monetization:

  1. Adicione webhooks que definam os gerenciadores de callback para os eventos de notificação usando o interface ou API.
  2. Configure o gerenciador de callback.
  3. Configure a notificação para um plano de tarifas ajustáveis usando o interface ou API.

Como gerenciar webhooks

Adicione e gerencie webhooks que definem os gerenciadores de callback para os eventos de notificação usando o interface ou API.

Como gerenciar webhooks usando a interface

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

Como explorar 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 que você:

Edge clássico (nuvem privada)

Para acessar a página "Webhooks" usando a IU do Classic 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" é 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 informações a seguir (todos os campos são obrigatórios).
    Campo Descrição
    Nome Nome do webhook.
    URL URL do gerenciador de retorno de chamada que será chamado quando a notificação do evento for acionada. Consulte Como configurar o gerenciador de callback.
  4. Clique em Salvar.

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

Editar um webhook usando a 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 alterne a chave de status para ativá-lo ou desativá-lo.

Como excluir um webhook usando a interface

Para excluir um webhook usando a UI:

  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.

Visualizar todos os webhooks usando o API

Veja 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 ver um webhook usando o API

Veja um único webhook emitindo 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 o API

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

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

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"
}

Editar um webhook usando a API

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

Por exemplo, o comando a seguir atualiza o gerenciador de callback associado 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

Ativar ou desativar 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 quando ocorre um evento.

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"
}

Excluir um webhook usando o API

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

Para especificar se deve ou não forçar a exclusão do webhook se houver processos em progresso, defina o parâmetro de consulta forceDelete como true ou false O parâmetro de consulta forceDelete está ativado (true) por padrão.

Por exemplo, o código a seguir 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

Como configurar o gerenciador de callback

O exemplo a seguir mostra o formato da solicitação JSON enviada ao gerenciador de callback. definido por um webhook quando uma notificação de evento é acionada. Verifique se a chamada de retorno processa 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 tarifas ajustável

Configure notificações com webhooks para um plano de tarifas ajustáveis com o interface ou API.

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

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

Acesse a caixa de diálogo "Notificações" para conferir um plano de tarifas 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 taxas de notificação ajustável, conforme descrito em Especificar detalhes do plano de notificação ajustável.
  2. Acesse a página "Planos de preços" selecionando Publicar > Monetização > de tarifas na barra de navegação à esquerda.
  3. Posicione o cursor sobre o plano de taxa de notificação ajustável publicado para exibir as ações.
  4. Clique em +Notificar.

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

    Observação: o plano de tarifas 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 ver os planos de tarifas.
  3. Clique em +Notificar na coluna "Ações" do plano de tarifas.

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

Adicionar notificações para um plano de tarifas ajustável usando a interface

Para adicionar notificações para um plano de tarifas ajustáveis na interface:

  1. Acesse a caixa de diálogo Notificações.
  2. Defina a condição de notificação em Intervalos de notificação por: especificando uma porcentagem do número alvo de transações em que você quer que a notificação seja acionada. Especificamente:
    • Para definir um valor exato, insira o valor no campo At/De %. e deixe o campo To % em branco.
    • Para definir um intervalo de porcentagem, insira a porcentagem inicial e final no Campos At/From % e To %, respectivamente, e um incremento no campo Step %. Por padrão, as notificações são enviadas em 10% incrementos no intervalo especificado.

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

  3. Para definir outras condições de notificação, clique em +Adicionar e repita a etapa 4)
  4. Selecione um ou mais itens para definir a ação de notificação em Webhooks. webhooks para gerenciar o tratamento de callbacks quando as notificações são acionadas.
  5. Clique em Criar notificação.

Editar notificações de um plano de tarifas ajustável usando a interface

Para editar as notificações de um plano de tarifas ajustáveis na interface:

  1. Acesse a caixa de diálogo Notificações.
  2. Clique em +Notificar na coluna "Ações" do plano de tarifas.
  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 tarifas 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 tarifas.
  3. Clique em Excluir notificação.

Configurar notificações para um plano de tarifas ajustáveis usando o API

Para configurar uma notificação para um plano de tarifas ajustáveis usando a API, siga o procedimento descritas em Gerenciamento condições e ações de notificação usando a API e os atributos descritos nesta seção.

Para configurar a condição de notificação (notificationCondition), use o seguintes valores de atributo. Para mais informações, consulte Configuração para condições de notificação.

Atributo Valor
RATEPLAN ID do plano de taxa de notificação ajustável.
PUBLISHED TRUE para indicar que o plano de taxa de notificação ajustável precisa ser publicadas.
UsageTarget É a porcentagem do número desejado de transações em que você quer receber uma notificação ser acionada.

Este atributo permite que você notifique os desenvolvedores quando eles estiverem se aproximando ou o número alvo de transações para um plano de tabela de preços com notificação ajustável que que compraram. Por exemplo, se um desenvolvedor comprou uma notificação ajustável do plano de preços e o número de transações para o desenvolvedor foi definido como 1.000, você pode notificá-los quando atingirem 800 transações (80% da meta do número de transações), 1.000 transações (100%) ou 1.500 transações (150%).

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

Para configurar a ação de notificação, em actions, defina os seguintes valores. Para Para mais informações, consulte 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, Como criar webhooks usando a API.

Veja a seguir um exemplo de como criar uma condição de notificação que aciona uma webhook quando a porcentagem do número alvo de transações atinge 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 informações sobre como visualizar, atualizar e excluir uma condição e ação de notificação, consulte:

Códigos de resposta do webhook

Veja 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 repetir a solicitação até três vezes em cinco minutos em intervalos de IP.

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