Configurar notificações usando webhooks

Você está lendo 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 ao uso dos 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 estas etapas usando a interface de gerenciamento do Edge ou a API Management and Monetization:

1. Adicione webhooks que definam os gerenciadores 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 taxas ajustável usando a interface ou a API.

Como gerenciar webhooks

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

Como gerenciar webhooks usando a interface

Adicione e gerencie webhooks que definam 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"
• Como adicionar um webhook usando a interface
• Como editar um webhook usando a interface
• Como excluir um webhook usando a interface

Como explorar a página "Webhooks"

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

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 será adicionado à lista e ativado por padrão.

Como 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 ativar ou desativar.

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 será 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
• Como visualizar um webhook usando a API
• Como adicionar um webhook usando a API
• Como editar um webhook usando a API
• Como excluir um webhook usando a API

Como visualizar todos os webhooks usando a API

Para visualizar todos os webhooks, emita 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 visualizar 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

Confira 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

Para adicionar um webhook, emita 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 de 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

Confira 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

Para editar um webhook, emita 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

Confira 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

Para ativar ou desativar um webhook, emita uma solicitação POST para /mint/organizations/{org_name}/webhooks/{webhook_id}, como 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 código 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

Confira 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

Para excluir um webhook, emita uma solicitação DELETE para /mint/organizations/{org_name}/webhooks/{webhook_id}.

Para especificar se a exclusão do webhook deve ser forçada ou não se houver processos em andamento, 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 código 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. É necessário garantir que o gerenciador de callback processe a solicitação de maneira adequada.

{
        "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 taxas ajustável

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

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

Configure 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" para um plano de taxas ajustável

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

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

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

1. Acesse a caixa de diálogo "Notificações".
2. Defina a condição de notificação em Intervalos de notificação especificando uma porcentagem do número de transações de destino em que você quer que uma notificação seja acionada. Especificamente:
   • Para definir uma porcentagem exata, insira a porcentagem no campo Em/De % e deixe o campo Para % em branco.
   • Para definir um intervalo de porcentagem, insira a porcentagem inicial e final nos campos Em/De % e Para %, respectivamente, e um valor de incremento no campo Etapa %. 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 de destino que 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 para um plano de taxas ajustável usando a interface

Para editar notificações para um plano de taxas ajustável usando a interface:

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

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

Para excluir uma condição e 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 taxas.
3. Clique em Excluir notificação.

Como configurar notificações para um plano de taxas 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 seguintes valores de atributo. Para mais informações, consulte Configuração propriedades para condições de notificação.

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.

O código a seguir mostra um exemplo de como criar uma condição de notificação que aciona um webhook quando a porcentagem do número de transações de destino 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:

• Como visualizar uma condição e ação de notificação usando a API
• Como editar uma condição e ação de notificação usando a API
• Como excluir uma condição e ação de notificação usando a API

Códigos de resposta do webhook

A seguir, resumimos os códigos de resposta do webhook e como eles são interpretados pelo sistema.