AWS Lambda Invoke

Have Convoy invoke your Lambda function with the result when a cargo completes — no webhook endpoint, no polling. From your side, the function simply “fires when the cargo is done”, receiving the standard result envelope as its event.

your code ── POST /cargo/load ──▶ Convoy ──▶ …batch processing…
                                    │
                                    ▼  cargo completes
                       AssumeRole(your role, ExternalId)
                                    │
                                    ▼
                lambda:InvokeFunction(InvocationType='Event',
                                      Payload=<result envelope>)
                                    │
                                    ▼
                    your function runs with the result

Convoy assumes the IAM role from your AWS connection and calls lambda:InvokeFunction asynchronously (InvocationType='Event'). Convoy’s delivery responsibility ends at the 202 from the Lambda front-end — after that, Lambda’s own async invoke machinery owns execution: its per-function retries (2 by default) and your configured on-failure destination  or DLQ.

Setup

{
  "Effect": "Allow",
  "Action": "lambda:InvokeFunction",
  "Resource": [
    "arn:aws:lambda:us-east-1:123456789012:function:on-cargo-done",
    "arn:aws:lambda:us-east-1:123456789012:function:on-cargo-done:*"
  ]
}

curl -X POST https://api.cnvy.ai/cargo/load \
  -H "X-API-Key: $CONVOY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "model": "claude-haiku-4-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Summarize this document…"}]
    },
    "callback": {
      "type": "aws_lambda_invoke",
      "connection_id": "awsconn_…",
      "function_arn": "arn:aws:lambda:us-east-1:123456789012:function:on-cargo-done:$LATEST"
    }
  }'

The handler

Your function receives the result envelope directly as event:

def handler(event, context):
    if event["success"]:
        response = event["response"]
        if response is None and event["response_truncated"]:
            # Oversize result — fetch from the hosted results mailbox
            response = fetch(event["result_url"])
        process(response)
    else:
        # Failure cargo delivers through the SAME invoke, with
        # success=false and an error_message — there is no separate
        # failure API for this target.
        handle_failure(event["cargo_id"], event["error_message"])

Envelope fields:

Async invoke accepts payloads up to 256 KB; Convoy’s 240 KB inline budget keeps every envelope under it — oversize responses ship the result_url pointer instead.

At-least-once: dedupe on cargo_id

InvokeFunction(Event) is not idempotent. If Convoy’s delivery times out after Lambda accepted the invoke but before the 202 arrived, the delivery retries and your function may run twice (Lambda’s own async retries can also re-run it). If duplicate processing matters, dedupe on cargo_id — one DynamoDB conditional put:

import boto3
from botocore.exceptions import ClientError
 
table = boto3.resource("dynamodb").Table("processed-cargo")
 
def handler(event, context):
    try:
        table.put_item(
            Item={"cargo_id": event["cargo_id"]},
            ConditionExpression="attribute_not_exists(cargo_id)",
        )
    except ClientError as e:
        if e.response["Error"]["Code"] == "ConditionalCheckFailedException":
            return  # already processed — duplicate delivery
        raise
    process(event)

Delivery semantics

• Both success and failure cargo invoke your function — branch on event["success"].
• Retries: transient AWS errors (throttles, 5xx) retry up to 5 times with exponential backoff (1, 3, 9, then 27 minutes between attempts — roughly 40 minutes end to end). Terminal conditions (function deleted, invoke grant removed, broken function KMS key) stop immediately and mark the cargo callback_failed.
• Recovery: the result stays retrievable via GET /cargo/{cargo_id}/result regardless of delivery outcome.

Troubleshooting