{"id":517,"date":"2026-10-28T16:05:47","date_gmt":"2026-10-28T16:05:47","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/download-media-whatsapp-webhook\/"},"modified":"2026-10-28T16:05:59","modified_gmt":"2026-10-28T16:05:59","slug":"download-media-whatsapp-webhook","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/en\/download-media-whatsapp-webhook\/","title":{"rendered":"How to receive and download media customers send through the WhatsApp API"},"content":{"rendered":"\n

Updated on October 28, 2026<\/em><\/p>\n\n\n\n

When a customer sends a photo, PDF, audio or video, the WhatsApp Business API webhook does not include the file: it includes a media ID<\/strong>. To download it, call GET \/{media-id}<\/code> to get a temporary URL, which expires after 5 minutes<\/strong>, then GET<\/code> that URL with your access token in the Authorization<\/code> header. Since a media ID received via webhook is only valid for 7 days<\/strong>, download right away and keep the file in your own storage.<\/p>\n\n\n\n

This guide covers the full flow, the fields for each media type, size limits, how to check file integrity, and examples in cURL, Node.js and Python, including uploading to Amazon S3.<\/p>\n\n\n\n

The flow in 4 steps<\/h2>\n\n\n\n
    \n
  1. Webhook<\/strong>: a message arrives with type<\/code> set to image<\/code>, document<\/code>, audio<\/code>, video<\/code> or sticker<\/code>, carrying the media id<\/code>.<\/li>\n\n\n
  2. Temporary URL<\/strong>: GET https:\/\/graph.facebook.com\/v26.0\/{media-id}<\/code> returns url<\/code>, mime_type<\/code>, sha256<\/code> and file_size<\/code>.<\/li>\n\n\n
  3. Download<\/strong>: GET<\/code> the url<\/code> with Authorization: Bearer <token><\/code>. Without the token, the request fails.<\/li>\n\n\n
  4. Storage<\/strong>: save it to your storage (S3, GCS, disk) and store the file path in your database, never Meta’s URL.<\/li>\n\n<\/ol>\n\n\n\n

    The time limits come from Meta’s media documentation<\/a>: media URLs expire after 5 minutes (after that, query the media ID again for a new one), media IDs from webhooks expire after 7 days, and media IDs from uploads expire after 30 days.<\/p>\n\n\n\n

    What arrives in the webhook<\/h2>\n\n\n\n

    This is the shape of an incoming image, per the image message webhook reference<\/a> (sample values):<\/p>\n\n\n\n

    {\n  \"object\": \"whatsapp_business_account\",\n  \"entry\": [{\n    \"id\": \"WABA_ID\",\n    \"changes\": [{\n      \"field\": \"messages\",\n      \"value\": {\n        \"messaging_product\": \"whatsapp\",\n        \"metadata\": {\n          \"display_phone_number\": \"15550783881\",\n          \"phone_number_id\": \"PHONE_NUMBER_ID\"\n        },\n        \"contacts\": [{ \"profile\": { \"name\": \"Maria\" }, \"wa_id\": \"16505551234\" }],\n        \"messages\": [{\n          \"from\": \"16505551234\",\n          \"id\": \"wamid.HBgLMTY1...\",\n          \"timestamp\": \"1761650000\",\n          \"type\": \"image\",\n          \"image\": {\n            \"caption\": \"Receipt\",\n            \"mime_type\": \"image\/jpeg\",\n            \"sha256\": \"SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=\",\n            \"id\": \"1003383421387256\",\n            \"url\": \"https:\/\/lookaside.fbsbx.com\/whatsapp_business\/attachments\/?mid=...\"\n          }\n        }]\n      }\n    }]\n  }]\n}<\/code><\/pre>\n\n\n\n
    The object name changes with the type (image<\/code>, document<\/code>, audio<\/code>, video<\/code>, sticker<\/code>), but the structure is similar. Documents also include filename<\/code>, handy for saving with the original name.<\/p>\n\n\n\n
    Note the url<\/code> field. Meta started rolling it out gradually in the webhook itself on November 12, 2025, which lets you skip step 2 and download directly with your token. Because the rollout is gradual, your code should work with and without it: use url<\/code> when present and, if it is missing or the download fails, query the media ID.<\/p>\n\n\n\n
    Field<\/th>What it is for<\/th><\/tr><\/thead>
    id<\/code><\/td>Media ID; use it to generate the download URL<\/td><\/tr>
    mime_type<\/code><\/td>File type (image\/jpeg<\/code>, application\/pdf<\/code>, audio\/ogg<\/code>…)<\/td><\/tr>
    sha256<\/code><\/td>File hash, to check integrity<\/td><\/tr>
    caption<\/code><\/td>Caption sent by the customer, if any<\/td><\/tr>
    filename<\/code><\/td>Original name (documents)<\/td><\/tr>
    url<\/code><\/td>Direct download URL, in gradual rollout<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Types and size limits<\/h2>\n\n\n\n
    This table summarizes supported types and maximum sizes from Meta’s media page. Use it to size your storage and download timeouts:<\/p>\n\n\n\n
    Type<\/th>Formats<\/th>Max size<\/th><\/tr><\/thead>
    Audio<\/td>AAC, AMR, MP3, M4A, OGG (OPUS codec only, mono)<\/td>16 MB<\/td><\/tr>
    Document<\/td>TXT, XLS, XLSX, DOC, DOCX, PPT, PPTX, PDF<\/td>100 MB<\/td><\/tr>
    Image<\/td>JPEG, PNG (8-bit, RGB or RGBA)<\/td>5 MB<\/td><\/tr>
    Sticker<\/td>WebP<\/td>500 KB animated, 100 KB static<\/td><\/tr>
    Video<\/td>3GP, MP4 (H.264 and AAC)<\/td>16 MB<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    Voice notes arrive as audio<\/code> messages. If you pass audio to a transcription service, check the mime_type<\/code> you received and whether the service accepts that format; if not, convert it first.<\/p>\n\n\n\n
    cURL example<\/h2>\n\n\n\n
    Step 2, get the URL:<\/p>\n\n\n\n
    curl \"https:\/\/graph.facebook.com\/v26.0\/1003383421387256\" \\\n  -H \"Authorization: Bearer $TOKEN\"<\/code><\/pre>\n\n\n\n
    Response:<\/p>\n\n\n\n
    {\n  \"messaging_product\": \"whatsapp\",\n  \"url\": \"https:\/\/lookaside.fbsbx.com\/whatsapp_business\/attachments\/?mid=...\",\n  \"mime_type\": \"image\/jpeg\",\n  \"sha256\": \"SfInY0gGKTsJlUWbwxC1k+FAD0FZHvzwfpvO0zX0GUI=\",\n  \"file_size\": 303833,\n  \"id\": \"1003383421387256\"\n}<\/code><\/pre>\n\n\n\n
    Step 3, download:<\/p>\n\n\n\n
    curl -L \"RETURNED_URL\" \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -o receipt.jpg<\/code><\/pre>\n\n\n\n
    Optionally, pass phone_number_id<\/code> as a query parameter in step 2: Meta then processes the request only if the media belongs to that number, a useful safeguard when one application serves several numbers.<\/p>\n\n\n\n
    Node.js example<\/h2>\n\n\n\n
    import crypto from 'node:crypto';\nimport { S3Client, PutObjectCommand } from '@aws-sdk\/client-s3';\n\nconst GRAPH = 'https:\/\/graph.facebook.com\/v26.0';\nconst TOKEN = process.env.WHATSAPP_TOKEN;\nconst s3 = new S3Client({ region: process.env.AWS_REGION });\n\nasync function getMediaUrl(mediaId) {\n  const res = await fetch(`${GRAPH}\/${mediaId}`, {\n    headers: { Authorization: `Bearer ${TOKEN}` },\n  });\n  if (!res.ok) throw new Error(`media ${mediaId}: HTTP ${res.status}`);\n  return res.json(); \/\/ { url, mime_type, sha256, file_size, id }\n}\n\nasync function download(url) {\n  const res = await fetch(url, { headers: { Authorization: `Bearer ${TOKEN}` } });\n  if (!res.ok) throw Object.assign(new Error('download failed'), { status: res.status });\n  return Buffer.from(await res.arrayBuffer());\n}\n\nexport async function saveMedia(media, key) {\n  let info = { url: media.url, sha256: media.sha256, mime_type: media.mime_type };\n  let file;\n  try {\n    if (!info.url) throw new Error('no url in webhook');\n    file = await download(info.url);\n  } catch {\n    info = await getMediaUrl(media.id); \/\/ fresh URL\n    file = await download(info.url);\n  }\n\n  const hash = crypto.createHash('sha256').update(file).digest('base64');\n  if (info.sha256 && hash !== info.sha256) throw new Error('hash mismatch');\n\n  await s3.send(new PutObjectCommand({\n    Bucket: process.env.BUCKET,\n    Key: key,\n    Body: file,\n    ContentType: info.mime_type,\n  }));\n  return key;\n}<\/code><\/pre>\n\n\n\n
    In Meta’s examples the sha256<\/code> value is base64-encoded, which is why the comparison uses digest('base64')<\/code>. If you see a different format in your traffic, log both values before turning the check on.<\/p>\n\n\n\n
    Python example<\/h2>\n\n\n\n
    import base64\nimport hashlib\nimport os\n\nimport boto3\nimport httpx\n\nGRAPH = \"https:\/\/graph.facebook.com\/v26.0\"\nTOKEN = os.environ[\"WHATSAPP_TOKEN\"]\nHEADERS = {\"Authorization\": f\"Bearer {TOKEN}\"}\ns3 = boto3.client(\"s3\")\n\n\ndef get_media_url(client: httpx.Client, media_id: str) -> dict:\n    r = client.get(f\"{GRAPH}\/{media_id}\", headers=HEADERS)\n    r.raise_for_status()\n    return r.json()\n\n\ndef save_media(media: dict, key: str) -> str:\n    with httpx.Client(timeout=60, follow_redirects=True) as client:\n        info = get_media_url(client, media[\"id\"])\n        r = client.get(info[\"url\"], headers=HEADERS)\n        if r.status_code == 404:  # expired URL: get a new one and retry\n            info = get_media_url(client, media[\"id\"])\n            r = client.get(info[\"url\"], headers=HEADERS)\n        r.raise_for_status()\n\n    computed = base64.b64encode(hashlib.sha256(r.content).digest()).decode()\n    if info.get(\"sha256\") and computed != info[\"sha256\"]:\n        raise ValueError(\"hash mismatch\")\n\n    s3.put_object(\n        Bucket=os.environ[\"BUCKET\"],\n        Key=key,\n        Body=r.content,\n        ContentType=info[\"mime_type\"],\n    )\n    return key<\/code><\/pre>\n\n\n\n
    For documents up to 100 MB, holding everything in memory can get heavy. In that case, stream the download to a temporary file and use boto3’s upload_fileobj<\/code>, or Upload<\/code> from @aws-sdk\/lib-storage<\/code> in Node, both of which upload in parts.<\/p>\n\n\n\n
    Where this fits in your architecture<\/h2>\n\n\n\n
    Do not download media inside the webhook request. The endpoint should validate the signature, enqueue the event and return 200<\/code> quickly; a separate worker handles download and upload. That way a large video does not stall the webhook or trigger retries from Meta. For the validation part, see how to validate the webhook signature<\/a>.<\/p>\n\n\n\n
    Some good practices:<\/p>\n\n\n\n