"` |
| `requestContext.http` | Um objeto que contém detalhes sobre a solicitação HTTP. | |
| `requestContext.http.method` | O método HTTP usado na solicitação. Os valores válidos incluem `GET`, `POST`, `PUT`, `HEAD`, `OPTIONS`, `PATCH` e `DELETE`. | `GET` |
| `requestContext.http.path` | O caminho da solicitação. Por exemplo, se o URL de solicitação for `https://{url-id}.lambda-url.{region}.on.aws/example/test/demo`, o valor do caminho será `/example/test/demo`. | `/example/test/demo` |
| `requestContext.http.protocol` | O protocolo da solicitação. | `HTTP/1.1` |
| `requestContext.http.sourceIp` | O endereço IP de origem da conexão TCP imediata que está fazendo a solicitação. | `123.123.123.123` |
| `requestContext.http.userAgent` | O valor do cabeçalho da solicitação User-Agent. | `Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/42.0` |
| `requestContext.requestId` | O ID da solicitação da invocação. Você pode usar esse ID para logs de invocações relacionadas à função. | `e1506fd5-9e7b-434f-bd42-4f8fa224b599` |
| `requestContext.routeKey` | URLs de função não usam esse parâmetro. O Lambda define isso como `$default` para marcar um espaço reservado. | `$default` |
| `requestContext.stage` | URLs de função não usam esse parâmetro. O Lambda define isso como `$default` para marcar um espaço reservado. | `$default` |
| `requestContext.time` | O timestamp da solicitação. | `"07/Sep/2021:22:50:22 +0000"` |
| `requestContext.timeEpoch` | O timestamp da solicitação, no horário da era UNIX. | `"1631055022677"` |
| `body` | O corpo da solicitação. Se o tipo de conteúdo da solicitação for binário, o corpo será codificado na base 64. | `{"key1": "value1", "key2": "value2"}` |
| `pathParameters` | URLs de função não usam esse parâmetro. O Lambda define isso como `null` ou exclui isso do JSON. | `null` |
| `isBase64Encoded` | `TRUE` se o corpo for uma carga útil binária e for codificado na base 64. `FALSE` nos demais casos. | `FALSE` |
| `stageVariables` | URLs de função não usam esse parâmetro. O Lambda define isso como `null` ou exclui isso do JSON. | `null` |
### Formato de carga útil de resposta
Quando a função retorna uma resposta, o Lambda analisa a resposta e converte-a em uma resposta HTTP. As cargas úteis de resposta de função têm o seguinte formato:
```
{
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": "{ \"message\": \"Hello, world!\" }",
"cookies": [
"Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
"Cookie_2=Value2; Max-Age=78000"
],
"isBase64Encoded": false
}
```
O Lambda infere o formato de resposta para você. Se a função do Lambda retornar JSON válido e não retornar um `statusCode`, o Lambda pressupõe o seguinte:
+ `statusCode` is `200`.
**nota**
Os `statusCode` válidos vão de 100 a 599.
+ `content-type` is `application/json`.
+ `body` é a resposta da função.
+ `isBase64Encoded` is `false`.
Os exemplos a seguir mostram como a saída da função do Lambda é mapeada para a carga útil da resposta e como a carga útil da resposta é mapeada para a resposta HTTP final. Quando o cliente invoca o URL de função, ele vê a resposta HTTP.
**Exemplo de saída para uma resposta de string**
| Saída da função do Lambda | Saída de resposta interpretada | Resposta HTTP (o que o cliente vê) |
| --- | --- | --- |
| "Hello, world!"
| {
"statusCode": 200,
"body": "Hello, world!",
"headers": {
"content-type": "application/json"
},
"isBase64Encoded": false
} | HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 15
"Hello, world!"
|
**Exemplo de saída para uma resposta em JSON**
| Saída da função do Lambda | Saída de resposta interpretada | Resposta HTTP (o que o cliente vê) |
| --- | --- | --- |
| {
"message": "Hello, world!"
} | {
"statusCode": 200,
"body": {
"message": "Hello, world!"
},
"headers": {
"content-type": "application/json"
},
"isBase64Encoded": false
} | HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 34
{
"message": "Hello, world!"
}
|
**Exemplo de saída para uma resposta personalizada**
| Saída da função do Lambda | Saída de resposta interpretada | Resposta HTTP (o que o cliente vê) |
| --- | --- | --- |
| {
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": JSON.stringify({
"message": "Hello, world!"
}),
"isBase64Encoded": false
} | {
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": JSON.stringify({
"message": "Hello, world!"
}),
"isBase64Encoded": false
} | HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value
{
"message": "Hello, world!"
}
|
### Cookies
Para retornar cookies da função, não adicione manualmente cabeçalhos `set-cookie`. Em vez disso, inclua os cookies no objeto de carga útil da resposta. O Lambda interpreta isso automaticamente e adiciona-os como cabeçalhos `set-cookie` na resposta HTTP, como no exemplo a seguir.
| Saída da função do Lambda | Resposta HTTP (o que o cliente vê) |
| --- | --- |
| {
"statusCode": 201,
"headers": {
"Content-Type": "application/json",
"My-Custom-Header": "Custom Value"
},
"body": JSON.stringify({
"message": "Hello, world!"
}),
"cookies": [
"Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
"Cookie_2=Value2; Max-Age=78000"
],
"isBase64Encoded": false
} | HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value
set-cookie: Cookie_1=Value2; Expires=21 Oct 2021 07:48 GMT
set-cookie: Cookie_2=Value2; Max-Age=78000
{
"message": "Hello, world!"
}
|
# Monitorar URLs de função do Lambda
Você pode usar o AWS CloudTrail e o Amazon CloudWatch para monitorar os URLs de função.
**Topics**
+ [
## Monitorar URLs de função com o CloudTrail
](#urls-cloudtrail)
+ [
## Métricas do CloudWatch para URLs de função
](#urls-cloudwatch)
## Monitorar URLs de função com o CloudTrail
Para URLs de função, o Lambda é automaticamente compatível com o registro das seguintes operações de API como eventos nos arquivos de log do CloudTrail:
+ [CreateFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_CreateFunctionUrlConfig.html)
+ [UpdateFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_UpdateFunctionUrlConfig.html)
+ [DeleteFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_DeleteFunctionUrlConfig.html)
+ [GetFunctionUrlConfig](https://docs.aws.amazon.com/lambda/latest/api/API_GetFunctionUrlConfig.html)
+ [ListFunctionUrlConfigs](https://docs.aws.amazon.com/lambda/latest/api/API_ListFunctionUrlConfigs.html)
Toda entrada de log contém informações sobre a identidade do chamador, quando a solicitação foi feita e outros detalhes. Você pode ver todos os eventos nos últimos 90 dias visualizando o **Event history** (Histórico de eventos) do CloudTrail. Para reter registros por mais de 90 dias, você pode criar uma trilha.
Por padrão, o CloudTrail não registra solicitações `InvokeFunctionUrl`, que são consideradas eventos de dados. Porém, você pode ativar o registro de eventos de dados no CloudTrail. Para obter mais informações, consulte [Registro eventos de dados em logs para trilhas](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html) no *Guia do usuário do AWS CloudTrail*.
## Métricas do CloudWatch para URLs de função
O Lambda envia métricas agregadas sobre solicitações de URL de função para o CloudWatch. Com essas métricas, você pode monitorar os URLs de função, criar painéis e configurar alarmes no console do CloudWatch.
Os URLs de função são compatíveis as seguintes métricas de invocação. Recomendamos visualizar essas métricas com a estatística `Sum`.
+ `UrlRequestCount`: o número de solicitações feitas a esse URL de função.
+ `Url4xxCount`: o número de solicitações que retornaram um código de status HTTP 4XX. Os códigos da série 4XX indicam erros do lado do cliente, como solicitações incorretas.
+ `Url5xxCount`: o número de solicitações que retornaram um código de status HTTP 5XX. Os códigos da série 5XX indicam erros do lado do servidor, como erros de função e de tempo limite.
Os URLs de função também são compatíveis com a métrica de performance a seguir. Recomendamos visualizar essas métricas com as estatísticas `Average` ou `Max`.
+ `UrlRequestLatency`: o tempo decorrido entre a hora que o URL de função recebe uma solicitação e a hora que o URL de função retorna uma resposta.
Cada uma dessas métricas de invocação e performance é compatível com as seguintes dimensões:
+ `FunctionName`: visualizar as métricas agregadas para os URLs de função atribuídos a uma versão da função não publicada `$LATEST` ou para qualquer um dos aliases da função. Por exemplo, `hello-world-function`.
+ `Resource`: visualizar as métricas para um URL de função específico. Isso é definido por um nome de função, junto com a versão da função não publicada `$LATEST` ou um dos aliases da função. Por exemplo, `hello-world-function:$LATEST`.
+ `ExecutedVersion`: visualizar as métricas para um URL de função específico com base na versão executada. Você pode usar essa dimensão principalmente para rastrear o URL de função atribuído à versão não publicada `$LATEST`.
# Seleção de um método para invocar a função do Lambda usando uma solicitação HTTP
Muitos casos de uso comuns do Lambda envolvem invocar a função usando uma solicitação HTTP. Por exemplo, você pode querer que uma aplicação Web invoque sua função por meio de uma solicitação do navegador. As funções do Lambda também podem ser usadas para criar APIs REST completas, lidar com interações do usuário em aplicativos móveis, processar dados de serviços externos por meio de chamadas HTTP ou criar webhooks personalizados.
As seções a seguir explicam quais são as opções para invocar o Lambda por meio de HTTP e fornecem informações para que você tome a decisão certa para seu caso de uso específico.
## Quais são suas opções ao selecionar um método de invocação HTTP?
O Lambda oferece dois métodos principais para invocar uma função usando uma solicitação HTTP: [URLs de função](urls-configuration.md) e o [API Gateway](services-apigateway.md). As principais diferenças entre ambos são as duas opções seguintes:
+ Os **URLs de função do Lambda** fornecem um endpoint HTTP simples e direto para uma função do Lambda. Eles são otimizados para proporcionar simplicidade e economia e fornecem o caminho mais rápido para expor uma função do Lambda via HTTP.
+ O **API Gateway** é um serviço mais avançado para criar APIs completas. O API Gateway é otimizado para criar e gerenciar APIs de produção em grande escala e fornece ferramentas abrangentes para segurança, monitoramento e gerenciamento de tráfego.
## Recomendações se você já conhece seus requisitos
Se você já sabe quais são seus requisitos, estas são as nossas recomendações básicas:
Recomendamos usar os **[URLs de funções](urls-configuration.md)** para aplicações simples ou prototipagem em que você só precisa de métodos básicos de autenticação e tratamento de solicitações/respostas e onde deseja ter o mínimo de custo e a complexidade.
O **[API Gateway](services-apigateway.md)** é a melhor opção para aplicações de produção em grande escala ou para casos em que você precisa de recursos mais avançados, como suporte à [descrição de OpenAPI](https://www.openapis.org/), opções de autenticação, nomes de domínio personalizados ou tratamento avançado de solicitações/respostas, incluindo controle de utilização, armazenamento em cache e transformação de solicitação/resposta.
## O que considerar ao selecionar um método para invocar a função do Lambda
Ao selecionar entre URLs de função e o API Gateway, você precisa considerar os seguintes fatores:
+ Suas necessidades de autenticação, como se você precisa do OAuth ou do Amazon Cognito para autenticar usuários
+ Seus requisitos de escalabilidade e a complexidade da API que deseja implementar
+ Se você precisa de recursos avançados, como validação de solicitação e formatação de solicitação/resposta
+ Seus requisitos de monitoramento
+ Suas metas de custo
Ao compreender esses fatores, você pode selecionar a opção que melhor equilibra seus requisitos de segurança, complexidade e custo.
As informações a seguir resumem as principais diferenças entre as duas opções.
### Autenticação
+ Os **URLs de função** fornecem opções básicas de autenticação por meio do AWS Identity and Access Management (IAM). Você pode configurar seus endpoints para serem públicos (sem autenticação) ou para exigirem a autenticação do IAM. Com a autenticação do IAM, você pode usar credenciais padrão da AWS ou perfis do IAM para controlar o acesso. Embora seja simples de configurar, essa abordagem oferece opções limitadas em comparação a outros métodos de autenticação.
+ O **API Gateway** fornece acesso a uma variedade maior de opções de autenticação. Além da autenticação do IAM, você pode usar [autorizadores do Lambda](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html) (lógica de autenticação personalizada), grupos de usuários do [Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/what-is-amazon-cognito.html) e fluxos do OAuth2.0. Essa flexibilidade permite que você implemente esquemas complexos de autenticação, incluindo provedores de autenticação terceirizados, autenticação baseada em tokens e autenticação multifator.
### Tratamento de solicitação/resposta
+ Os **URLs de função** fornecem tratamento básico para solicitações e respostas HTTP. Eles são compatíveis com métodos HTTP padrão e incluem suporte integrado para compartilhamento de recursos de origem cruzada (CORS). Embora consigam lidar com cargas úteis JSON e parâmetros de consulta naturalmente, eles não oferecem recursos de transformação ou validação de solicitações. O tratamento de respostas é igualmente simples: o cliente recebe a resposta da sua função do Lambda exatamente como o Lambda a retorna.
+ O **API Gateway** fornece recursos sofisticados de tratamento de solicitações e respostas. Você pode definir validadores de solicitações, transformar solicitações e respostas usando modelos de mapeamento, configurar cabeçalhos de solicitação/resposta e implementar o armazenamento em cache de respostas. O API Gateway também oferece suporte a cargas úteis binárias e nomes de domínio personalizados e pode modificar as respostas antes que elas cheguem ao cliente. Você pode configurar modelos para validação e transformação de solicitação/resposta usando o esquema JSON.
### Escalabilidade
+ Os **URLs de funções** escalam diretamente com os limites de simultaneidade da sua função do Lambda e lidam com picos de tráfego escalando sua função até o limite máximo de simultaneidade configurado. Quando esse limite é atingido, o Lambda responde a solicitações adicionais com respostas HTTP 429. Não há um mecanismo de enfileiramento integrado, portanto, lidar com a escalabilidade depende inteiramente da configuração da sua função do Lambda. Por padrão, as funções do Lambda têm um limite de mil execuções simultâneas por Região da AWS.
+ O **API Gateway** fornece recursos adicionais de escalabilidade além da própria escalabilidade do Lambda. Ele inclui recursos integrados de enfileiramento e controle de utilização, permitindo que você gerencie os picos de tráfego com mais tranquilidade. Por padrão, o API Gateway pode lidar com até 10 mil solicitações por segundo por região, com uma capacidade de expansão de 5 mil solicitações por segundo. Ele também fornece ferramentas para solicitações de controle de utilização em diferentes níveis (API, estágio ou método) para proteger seu backend.
### Monitoramento
+ Os **URLs de funções** oferecem monitoramento básico por meio de métricas do Amazon CloudWatch, incluindo contagem de solicitações, latência e taxas de erro. Você tem acesso às métricas e logs padrão do Lambda, que mostram as solicitações brutas que chegam à sua função. Embora isso forneça visibilidade operacional essencial, as métricas se concentram principalmente na execução da função.
+ O **API Gateway** fornece recursos abrangentes de monitoramento, incluindo métricas detalhadas, geração de logs e opções de rastreamento. Você pode monitorar chamadas de API, latência, taxas de erro e taxas de acerto/erro de cache por meio do CloudWatch. O API Gateway também se integra ao AWS X-Ray para rastreamento distribuído e fornece formatos de logs personalizáveis.
### Custo
+ Os **URLs de funções** seguem o modelo de preços padrão do Lambda: você paga somente pelas invocações de funções e pelo tempo de computação. Não há cobranças adicionais pelo endpoint do URL em si. Isso o torna uma opção econômica para APIs simples ou aplicações com pouco tráfego, caso você não precise dos recursos adicionais do API Gateway.
+ O **API Gateway** oferece um [nível gratuito](https://aws.amazon.com/api-gateway/pricing/#Free_Tier) que inclui um milhão de chamadas de API recebidas para APIs REST e um milhão de chamadas de API recebidas para APIs HTTP. Depois disso, o API Gateway cobra por chamadas de API, transferência de dados e armazenamento em cache (se habilitado). Consulte a [página de preços](https://aws.amazon.com/api-gateway/pricing/) do API Gateway para entender os custos do seu próprio caso de uso.
### Outros recursos
+ Os **URLs de funções** são projetados para oferecer simplicidade e integração direta com o Lambda. Eles são compatíveis com endpoints HTTP e HTTPS, oferecem suporte CORS integrado e fornecem endpoints de pilha dupla (IPv4 e IPv6). Embora não tenham recursos avançados, eles se destacam em cenários em que você precisa de uma forma rápida e direta de expor as funções do Lambda via HTTP.
+ O **API Gateway** inclui vários recursos adicionais, como versionamento de API, gerenciamento de estágios, chaves de API para planos de uso, documentação de API por meio do Swagger/OpenAPI, APIs de WebSocket, APIs privadas em uma VPC e integração com WAF para segurança extra. Ele também oferece suporte a implantações canário, integrações simuladas para testes e integração com outros Serviços da AWS além do Lambda.
## Seleção de um método para invocar a função do Lambda
Agora que você conhece os critérios para escolher entre URLs de funções do Lambda e o API Gateway, bem como as principais diferenças entre eles, você poderá selecionar a opção que melhor atende às suas necessidades e usar os recursos a seguir para ajudar a começar a usá-la.
------
#### [ Function URLs ]
**Conceitos básicos para usar URLs de funções com os recursos abaixo**
+ Siga o tutorial [Criar uma função do Lambda com um URL de função](urls-webhook-tutorial.md)
+ Saiba mais sobre URLs de funções no capítulo [Criar e gerenciar URLs de função do Lambda](urls-configuration.md) deste guia
+ Experimente o tutorial guiado no console **Criar um aplicativo Web simples** fazendo o seguinte:
1. Abra a [página de funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Abra o painel de ajuda escolhendo o ícone no canto superior direito da tela.
![\[\]](http://docs.aws.amazon.com/pt_br/lambda/latest/dg/images/console_help_screenshot.png)
1. Selecione **Tutoriais**.
1. Em **Criar um aplicativo Web simples**, escolha **Iniciar tutorial**.
------
#### [ API Gateway ]
**Conceitos básicos para usar o Lambda e o API Gateway com os recursos abaixo**
+ Siga o tutorial [Uso do Lambda com API Gateway](services-apigateway-tutorial.md) para criar uma API REST integrada a uma função do Lambda de backend.
+ Saiba mais sobre os diferentes tipos de API oferecidos pelo API Gateway nas seguintes seções do *Guia do desenvolvedor do Amazon API Gateway*:
+ [APIs REST do API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-rest-api.html)
+ [APIs HTTP do API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api.html)
+ [APIs de WebSocket do API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html)
+ Experimente um ou mais dos exemplos na seção [Tutoriais e workshops](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-tutorials.html) do *Guia do desenvolvedor do Amazon API Gateway*.
------
# Tutorial: criar um endpoint de webhook usando um URL de função do Lambda
Neste tutorial, você cria um URL de função do Lambda para implementar um endpoint de webhook. Um webhook é uma comunicação leve e orientada por eventos que envia dados automaticamente entre aplicações usando HTTP. Você pode usar um webhook para receber atualizações imediatas sobre eventos que acontecem em outro sistema, como quando um novo cliente se cadastra em um site, um pagamento é processado ou um arquivo é carregado.
Com o Lambda, os webhooks podem ser implementados usando URLs de funções do Lambda ou API Gateway. URLs de funções são uma boa opção para webhooks simples que não exigem atributos como autorização avançada ou validação de solicitações.
**dica**
Se não tiver certeza de qual é a melhor solução para seu caso de uso, consulte [Seleção de um método para invocar a função do Lambda usando uma solicitação HTTP](furls-http-invoke-decision.md).
## Pré-requisitos
Para concluir este tutorial, você deve ter Python (versão 3.8 ou posterior) ou Node.js (versão 18 ou posterior) instalado em sua máquina local.
Para testar o endpoint usando uma solicitação HTTP, o tutorial usa [curl](https://curl.se/), uma ferramenta de linha de comando que você pode usar para transferir dados usando vários protocolos de rede. Consulte a [documentação do curl](https://curl.se/docs/install.html) para saber como instalar a ferramenta, caso ainda não o tenha.
## Criar a função do Lambda
Primeiro, crie a função do Lambda que será executada quando uma solicitação HTTP for enviada para seu endpoint de webhook. Neste exemplo, a aplicação de envio envia uma atualização sempre que um pagamento é enviado e indica no corpo da solicitação HTTP se o pagamento foi bem-sucedido. A função do Lambda analisa a solicitação e age de acordo com o status do pagamento. Neste exemplo, o código apenas imprime o ID do pedido para o pagamento, mas em uma aplicação real, você pode adicionar o pedido a um banco de dados ou enviar uma notificação.
A função também implementa o método de autenticação mais comum usado para webhooks, a autenticação de mensagens baseada em hash (HMAC). Com esse método, as aplicações de envio e recebimento compartilham uma chave secreta. A aplicação de envio usa um algoritmo de hash para gerar uma assinatura exclusiva usando essa chave junto com o conteúdo da mensagem e inclui a assinatura na solicitação do webhook como um cabeçalho HTTP. A aplicação recebedora então repete essa etapa, gerando a assinatura usando a chave secreta, e compara o valor resultante com a assinatura enviada no cabeçalho da solicitação. Se o resultado corresponder, a solicitação será considerada legítima.
Crie a função usando o console do Lambda com o runtime do Python ou do Node.js.
------
#### [ Python ]
**Criar a função do Lambda**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Crie uma função básica "Hello world" fazendo o seguinte:
1. Escolha a opção **Criar função**.
1. Selecione **Criar do zero**.
1. Em **Function name** (Nome da função), insira **myLambdaWebhook**.
1. Em **Runtime**, escolha **Python3.14**.
1. Escolha a opção **Criar função**.
1. No painel **Código-fonte**, substitua o código existente copiando e colando o seguinte:
```
import json
import hmac
import hashlib
import os
def lambda_handler(event, context):
# Get the webhook secret from environment variables
webhook_secret = os.environ['WEBHOOK_SECRET']
# Verify the webhook signature
if not verify_signature(event, webhook_secret):
return {
'statusCode': 401,
'body': json.dumps({'error': 'Invalid signature'})
}
try:
# Parse the webhook payload
payload = json.loads(event['body'])
# Handle different event types
event_type = payload.get('type')
if event_type == 'payment.success':
# Handle successful payment
order_id = payload.get('orderId')
print(f"Processing successful payment for order {order_id}")
# Add your business logic here
# For example, update database, send notifications, etc.
elif event_type == 'payment.failed':
# Handle failed payment
order_id = payload.get('orderId')
print(f"Processing failed payment for order {order_id}")
# Add your business logic here
else:
print(f"Received unhandled event type: {event_type}")
# Return success response
return {
'statusCode': 200,
'body': json.dumps({'received': True})
}
except json.JSONDecodeError:
return {
'statusCode': 400,
'body': json.dumps({'error': 'Invalid JSON payload'})
}
except Exception as e:
print(f"Error processing webhook: {e}")
return {
'statusCode': 500,
'body': json.dumps({'error': 'Internal server error'})
}
def verify_signature(event, webhook_secret):
"""
Verify the webhook signature using HMAC
"""
try:
# Get the signature from headers
signature = event['headers'].get('x-webhook-signature')
if not signature:
print("Error: Missing webhook signature in headers")
return False
# Get the raw body (return an empty string if the body key doesn't exist)
body = event.get('body', '')
# Create HMAC using the secret key
expected_signature = hmac.new(
webhook_secret.encode('utf-8'),
body.encode('utf-8'),
hashlib.sha256
).hexdigest()
# Compare the expected signature with the received signature to authenticate the message
is_valid = hmac.compare_digest(signature, expected_signature)
if not is_valid:
print(f"Error: Invalid signature. Received: {signature}, Expected: {expected_signature}")
return False
return True
except Exception as e:
print(f"Error verifying signature: {e}")
return False
```
1. Na seção **DEPLOY**, escolha **Implantar** para atualizar o código da função.
------
#### [ Node.js ]
**Criar a função do Lambda**
1. Abra a [página Funções](https://console.aws.amazon.com/lambda/home#/functions) do console do Lambda.
1. Crie uma função básica "Hello world" fazendo o seguinte:
1. Escolha a opção **Criar função**.
1. Selecione **Criar do zero**.
1. Em **Function name** (Nome da função), insira **myLambdaWebhook**.
1. Em **Runtime**, selecione **nodejs24.x**.
1. Escolha a opção **Criar função**.
1. No painel **Código-fonte**, substitua o código existente copiando e colando o seguinte:
```
import crypto from 'crypto';
export const handler = async (event, context) => {
// Get the webhook secret from environment variables
const webhookSecret = process.env.WEBHOOK_SECRET;
// Verify the webhook signature
if (!verifySignature(event, webhookSecret)) {
return {
statusCode: 401,
body: JSON.stringify({ error: 'Invalid signature' })
};
}
try {
// Parse the webhook payload
const payload = JSON.parse(event.body);
// Handle different event types
const eventType = payload.type;
switch (eventType) {
case 'payment.success': {
// Handle successful payment
const orderId = payload.orderId;
console.log(`Processing successful payment for order ${orderId}`);
// Add your business logic here
// For example, update database, send notifications, etc.
break;
}
case 'payment.failed': {
// Handle failed payment
const orderId = payload.orderId;
console.log(`Processing failed payment for order ${orderId}`);
// Add your business logic here
break;
}
default:
console.log(`Received unhandled event type: ${eventType}`);
}
// Return success response
return {
statusCode: 200,
body: JSON.stringify({ received: true })
};
} catch (error) {
if (error instanceof SyntaxError) {
// Handle JSON parsing errors
return {
statusCode: 400,
body: JSON.stringify({ error: 'Invalid JSON payload' })
};
}
// Handle all other errors
console.error('Error processing webhook:', error);
return {
statusCode: 500,
body: JSON.stringify({ error: 'Internal server error' })
};
}
};
// Verify the webhook signature using HMAC
const verifySignature = (event, webhookSecret) => {
try {
// Get the signature from headers
const signature = event.headers['x-webhook-signature'];
if (!signature) {
console.log('No signature found in headers:', event.headers);
return false;
}
// Get the raw body (return an empty string if the body key doesn't exist)
const body = event.body || '';
// Create HMAC using the secret key
const hmac = crypto.createHmac('sha256', webhookSecret);
const expectedSignature = hmac.update(body).digest('hex');
// Compare expected and received signatures
const isValid = signature === expectedSignature;
if (!isValid) {
console.log(`Invalid signature. Received: ${signature}, Expected: ${expectedSignature}`);
return false;
}
return true;
} catch (error) {
console.error('Error during signature verification:', error);
return false;
}
};
```
1. Na seção **DEPLOY**, escolha **Implantar** para atualizar o código da função.
------
## Criar a chave secreta
Para que a função do Lambda autentique a solicitação do webhook, ela usa uma chave secreta que compartilha com a aplicação de chamada. Neste exemplo, a chave é armazenada em um variável de ambiente. Não inclua informações confidenciais, como senhas, no código de função, em uma aplicação em produção. Em vez disso, [crie um segredo do AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html) e [use a extensão do Lambda AWS Parameters and Secrets](with-secrets-manager.md) para recuperar suas credenciais na função do Lambda.
**Criar e armazenar a chave secreta do webhook**
1. Gere uma string longa e aleatória usando um gerador de números aleatórios criptograficamente seguro. Você pode usar os seguintes trechos de código em Python ou Node.js para gerar e imprimir um segredo de 32 caracteres, ou usar seu próprio método preferido.
------
#### [ Python ]
**Example código para gerar um segredo**
```
import secrets
webhook_secret = secrets.token_urlsafe(32)
print(webhook_secret)
```
------
#### [ Node.js ]
**Example código para gerar um segredo (formato de módulo ES)**
```
import crypto from 'crypto';
let webhookSecret = crypto.randomBytes(32).toString('base64');
console.log(webhookSecret)
```
------
1. Armazene sua string gerada como uma variável de ambiente para sua função fazendo o seguinte:
1. Na guia **Configurações** para sua função, selecione **Variáveis de ambiente**.
1. Escolha **Editar**.
1. Escolha **Add environment variable (Adicionar variável de ambiente)**.
1. Para **Chave**, insira **WEBHOOK\$1SECRET**, e para **Valor**, insira o segredo que você gerou na etapa anterior.
1. Escolha **Salvar**.
Você precisará usar esse segredo novamente em outro momento no tutorial para testar sua função, então anote-o agora.
## Criar o endpoint do URL da função
Criar um endpoint para seu webhook usando um URL da função do Lambda. Como você usa o tipo de autenticação `NONE` para criar um endpoint com acesso público, qualquer pessoa com o URL pode invocar sua função. Para saber mais sobre como controlar o acesso aos URLs das funções, consulte [Controlar o acesso aos URLs de função do Lambda](urls-auth.md). Se você precisar de opções de autenticação mais avançadas para seu webhook, considere usar o API Gateway.
**Criar o endpoint do URL da função**
1. Na guia **Configuração** para sua função, selecione **URL da função**.
1. Escolha **Create function URL** (Criar URL de função).
1. Para **Tipo de autenticação**, selecione **NONE**.
1. Escolha **Salvar**.
O endpoint do URL da função que você acabou de criar é exibido no painel **URL da função**. Copie o endpoint para usar posteriormente no tutorial.
## Testar a função no console
Antes de usar uma solicitação HTTP para invocar sua função usando o endpoint do URL, teste-a no console para confirmar se o código está funcionando conforme o esperado.
Para verificar a função no console, primeiro calcule uma assinatura de webhook usando o segredo gerado anteriormente no tutorial com a seguinte carga útil JSON de teste:
```
{
"type": "payment.success",
"orderId": "1234",
"amount": "99.99"
}
```
Use um dos exemplos de código Python ou Node.js a seguir para calcular a assinatura do webhook usando seu próprio segredo.
------
#### [ Python ]
**Calcular a assinatura do webhook**
1. Salve o código a seguir como um arquivo chamado `calculate_signature.py`. Substitua o segredo do webhook no código pelo seu próprio valor.
```
import secrets
import hmac
import json
import hashlib
webhook_secret = "arlbSDCP86n_1H90s0fL_Qb2NAHBIBQOyGI0X4Zay4M"
body = json.dumps({"type": "payment.success", "orderId": "1234", "amount": "99.99"})
signature = hmac.new(
webhook_secret.encode('utf-8'),
body.encode('utf-8'),
hashlib.sha256
).hexdigest()
print(signature)
```
1. Calcule a assinatura executando o comando a seguir no diretório onde você salvou o código. Copie a assinatura que o código gera.
```
python calculate_signature.py
```
------
#### [ Node.js ]
**Calcular a assinatura do webhook**
1. Salve o código a seguir como um arquivo chamado `calculate_signature.mjs`. Substitua o segredo do webhook no código pelo seu próprio valor.
```
import crypto from 'crypto';
const webhookSecret = "arlbSDCP86n_1H90s0fL_Qb2NAHBIBQOyGI0X4Zay4M"
const body = "{\"type\": \"payment.success\", \"orderId\": \"1234\", \"amount\": \"99.99\"}";
let hmac = crypto.createHmac('sha256', webhookSecret);
let signature = hmac.update(body).digest('hex');
console.log(signature);
```
1. Calcule a assinatura executando o comando a seguir no diretório onde você salvou o código. Copie a assinatura que o código gera.
```
node calculate_signature.mjs
```
------
Agora você pode testar o código da função usando uma solicitação HTTP de teste no console.
**Testar a função no console**
1. Selecione a guia **Code** para sua função.
1. Na seção **TEST EVENTS**, selecione **Create new test event**
1. Em **Event Name (Nome do evento)**, insira **myEvent**.
1. Substitua o JSON existente copiando e colando o seguinte no painel **JSON do evento**. Substitua a assinatura do webhook pelo valor calculado na etapa anterior.
```
{
"headers": {
"Content-Type": "application/json",
"x-webhook-signature": "2d672e7a0423fab740fbc040e801d1241f2df32d2ffd8989617a599486553e2a"
},
"body": "{\"type\": \"payment.success\", \"orderId\": \"1234\", \"amount\": \"99.99\"}"
}
```
1. Escolha **Salvar**.
1. Escolha **Invoke (Invocar)**.
Você deve ver uma saída semelhante a:
------
#### [ Python ]
```
Status: Succeeded
Test Event Name: myEvent
Response:
{
"statusCode": 200,
"body": "{\"received\": true}"
}
Function Logs:
START RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6 Version: $LATEST
Processing successful payment for order 1234
END RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6
REPORT RequestId: 50cc0788-d70e-453a-9a22-ceaa210e8ac6 Duration: 1.55 ms Billed Duration: 2 ms Memory Size: 128 MB Max Memory Used: 36 MB Init Duration: 136.32 ms
```
------
#### [ Node.js ]
```
Status: Succeeded
Test Event Name: myEvent
Response:
{
"statusCode": 200,
"body": "{\"received\":true}"
}
Function Logs:
START RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 Version: $LATEST
2025-01-10T18:05:42.062Z e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 INFO Processing successful payment for order 1234
END RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4
REPORT RequestId: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 Duration: 60.10 ms Billed Duration: 61 ms Memory Size: 128 MB Max Memory Used: 72 MB Init Duration: 174.46 ms
Request ID: e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4
```
------
## Testar a função usando uma solicitação HTTP
Use a ferramenta de linha de comando curl para testar seu endpoint de webhook.
**Testar a função usando solicitações HTTP**
1. Em um terminal ou programa shell, execute o seguinte comando curl. Substitua o URL pelo valor do endpoint do URL da sua própria função e substitua a assinatura do webhook pela assinatura que você calculou usando sua própria chave secreta.
```
curl -X POST https://ryqgmbx5xjzxahif6frvzikpre0bpvpf.lambda-url.us-west-2.on.aws/ \
-H "Content-Type: application/json" \
-H "x-webhook-signature: d5f52b76ffba65ff60ea73da67bdf1fc5825d4db56b5d3ffa0b64b7cb85ef48b" \
-d '{"type": "payment.success", "orderId": "1234", "amount": "99.99"}'
```
A seguinte saída deverá ser mostrada:
```
{"received": true}
```
1. Inspecione os logs do CloudWatch da sua função para confirmar se ela analisou a carga útil corretamente, fazendo o seguinte:
1. No console do Amazon CloudWatch, abra a página [Grupo de logs](https://console.aws.amazon.com/cloudwatch/home#logsV2:log-groups).
1. Selecione o grupo de logs da função (`/aws/lambda/myLambdaWebhook`).
1. Selecione o stream de logs mais recente.
Você deve ver uma saída semelhante à seguinte nos logs da sua função:
------
#### [ Python ]
```
Processing successful payment for order 1234
```
------
#### [ Node.js ]
```
2025-01-10T18:05:42.062Z e54fe6c7-1df9-4f05-a4c4-0f71cacd64f4 INFO Processing successful payment for order 1234
```
------
1. Confirme se seu código detecta uma assinatura inválida executando o seguinte comando curl. Substitua o URL pelo endpoint do URL da sua própria função.
```
curl -X POST https://ryqgmbx5xjzxahif6frvzikpre0bpvpf.lambda-url.us-west-2.on.aws/ \
-H "Content-Type: application/json" \
-H "x-webhook-signature: abcdefg" \
-d '{"type": "payment.success", "orderId": "1234", "amount": "99.99"}'
```
A seguinte saída deverá ser mostrada:
```
{"error": "Invalid signature"}
```
## Limpe os recursos
Agora você pode excluir os recursos criados para este tutorial, a menos que queira mantê-los. Excluindo os recursos da AWS que você não está mais usando, você evita cobranças desnecessárias em sua Conta da AWS.
**Como excluir a função do Lambda**
1. Abra a página [Functions](https://console.aws.amazon.com/lambda/home#/functions) (Funções) no console do Lambda.
1. Selecione a função que você criou.
1. Selecione **Actions**, **Delete**.
1. Digite **confirm** no campo de entrada de texto e escolha **Delete** (Excluir).
Quando você cria uma função do Lambda no console, o Lambda também cria um [perfil de execução](lambda-intro-execution-role.md) para essa função.
**Para excluir a função de execução**
1. Abra a página [Roles](https://console.aws.amazon.com/iam/home#/roles) (Funções) no console do IAM.
1. Selecione o perfil de execução que o Lambda criou. O perfil tem o formato de nome `myLambdaWebhook-role-`.
1. Escolha **Excluir**.
1. Insira o nome do perfil no campo de entrada de texto e escolha **Delete** (Excluir).