AWS S3 Object Delivery

Write the complete cargo result — no size cap — as a JSON object in your S3 bucket. Every other direct-AWS target inlines at most ~240 KB and falls back to a pointer for oversize results; S3 delivery ships the full response every time. And it doubles as a trigger for free: attach S3 Event Notifications (→ Lambda / SQS / EventBridge) to the prefix.

your code ── POST /cargo/load ──▶ Convoy ──▶ …batch processing…
                                    │
                                    ▼  cargo completes
                       AssumeRole(your role, ExternalId)
                                    │
                                    ▼
              s3:PutObject(Bucket: your-bucket,
                           Key: {key_prefix}{cargo_id}.json,
                           Body: <FULL result envelope>)
                                    │
                                    ▼
        S3 Event Notification on the prefix → Lambda / SQS / EventBridge
        (or your pipeline just reads the object)

Why S3 delivery:

• No size cap — the object always carries the complete response; response_truncated is always false. This is the target for large results.
• You own the data at rest — your bucket, your retention (lifecycle rules), your encryption, your access control, your data-residency story.
• Exactly-once effective — the object key is deterministic ({key_prefix}{cargo_id}.json), so a delivery retry simply overwrites the same object with identical bytes. (Buckets with versioning enabled will record a duplicate version — harmless.)
• Write-only, prefix-scoped — Convoy only ever gets s3:PutObject scoped to your agreed prefix. It can never read or list your bucket, and it cannot write outside the prefix even if your role policy is bucket-wide (each delivery session carries a prefix-scoped session policy on top of your role policy).

Object shape

The object metadata lets event-notification consumers and lifecycle tooling filter without reading the body.

Setup

{
  "Effect": "Allow",
  "Action": "s3:PutObject",
  "Resource": "arn:aws:s3:::acme-cargo-results/convoy/*"
}

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_s3",
      "connection_id": "awsconn_…",
      "bucket_arn": "arn:aws:s3:::acme-cargo-results",
      "key_prefix": "convoy/results/"
    },
    "metadata": {"job_id": "batch-2026-08-29"}
  }'

Triggering on delivery — S3 Event Notifications

Attach a notification to the prefix so an object write fires your consumer:

# SAM/CloudFormation — bucket notification → Lambda
ResultsBucket:
  Type: AWS::S3::Bucket
  Properties:
    BucketName: acme-cargo-results
    NotificationConfiguration:
      LambdaConfigurations:
        - Event: s3:ObjectCreated:Put
          Filter:
            S3Key:
              Rules:
                - Name: prefix
                  Value: convoy/results/
                - Name: suffix
                  Value: .json
          Function: !GetAtt OnCargoResult.Arn

Your consumer reads the object (or just its convoy-* metadata) and processes the full result:

import boto3, json
 
s3 = boto3.client("s3")
 
def handler(event, context):
    for record in event["Records"]:
        bucket = record["s3"]["bucket"]["name"]
        key = record["s3"]["object"]["key"]
        # Skip the verification probe object.
        if key.endswith("convoy-verify.json"):
            continue
        head = s3.head_object(Bucket=bucket, Key=key)
        if head["Metadata"].get("convoy-success") != "true":
            handle_failure(bucket, key)
            continue
        envelope = json.loads(
            s3.get_object(Bucket=bucket, Key=key)["Body"].read()
        )
        process(envelope["cargo_id"], envelope["response"], envelope["metadata"])

The result envelope

The object body is the same envelope every direct-AWS target uses — except response is always fully inlined here:

Failure cargo

There is no separate failure API — failed cargo writes the same deterministic key with success: false + error_message in the body and convoy-success: false in the object metadata, so consumers can branch on the metadata without reading the body.

Troubleshooting