Webhook Delivery

Webhooks allow you to receive API response data automatically — without polling. Instead of repeatedly calling an endpoint to check if a job has completed, you can register a webhook URL and receive the result pushed directly to your server.

Setup

1. Test Your Webhook URL

Before using a URL in your API calls, verify it is publicly reachable using the test endpoint:

POST https://dashboard.transcriptdownloader.com/api/webhook/test

Body:

{
    "url": "https://your-domain.com/webhook"
}

Success response — URL is reachable and returned a 2xx:

{
    "status": "success",
    "message": "Webhook URL is reachable and returned a successful response. You can now use this URL in your API calls.",
    "http_status": 200
}

Error response — URL is unreachable or returned a non-2xx:

{
    "status": "error",
    "message": "Your URL is reachable but returned HTTP 405 (Method Not Allowed). Make sure your endpoint accepts POST requests.",
    "http_status": 405
}

📋 Note: Private/internal addresses (localhost, 192.168.*, etc.) are blocked. The test sends a real POST request with a sample payload to verify reachability.

2. Pass include_webhook in Your Request

Add "include_webhook": "<your-url>" to the body of any supported API request. When the job completes (or fails), the full response payload will be POSTed to that URL.

{
    "youtube_video_id": "Fqdz6A-5d04",
    "include_webhook": "https://your-domain.com/webhook"
}

No global webhook URL configuration is required — the URL is passed directly with each request.

How It Works

• Your webhook URL receives a single POST request when the job completes or fails.
• The request body is the exact same JSON the API endpoint would return — no wrapper or envelope.
• Three custom HTTP headers are included so you can identify the event:

• If your endpoint returns 405 Method Not Allowed, the webhook will automatically retry as a GET request with the payload JSON-encoded in a payload query parameter.
• Failed deliveries are retried up to 3 times with backoff intervals of 10s, 30s, and 60s.

Supported Endpoints

All async endpoints support include_webhook. The webhook fires once when processing completes.

YouTube

Instagram

Request Headers Sent to Your Server

Every webhook delivery includes these headers:

Content-Type: application/json
User-Agent: TranscriptDownloader-Webhook/1.0
X-Webhook-Endpoint: downloads/audio
X-Webhook-Original-Status: 200
X-Webhook-Download-Id: 01JW72M0AGW3M6R3QDCS30RD2P

The payload body is the exact same JSON the API endpoint would return — see each endpoint’s documentation for the full response structure.

• YouTube API Documentation — downloads/audio, transcripts, transcriptspeakerid, channel/profile
• Instagram API Documentation — instagram/profile, instagram/content, instagram/list, instagram/audio

Retry Behaviour

After 3 failed attempts the delivery is permanently abandoned. Ensure your endpoint returns a 2xx status code promptly to acknowledge receipt.

Important Notes

• include_webhook must be passed at request time — it cannot be added after a job has started.
• The webhook fires once per job — on final success or final failure. No intermediate pending webhooks are sent.
• For instagram/list, two separate webhooks are fired — one when posts complete and one when reels complete. Each webhook contains only its own data (posts/reels) and a single download object for that type.
• The webhook URL is per-request — pass a different URL on each call if needed.
• Webhooks are delivered asynchronously via a background queue worker — delivery may take a few seconds after job completion.

Support

If you need assistance or have any questions, please contact our support team at https://transcriptdownloader.com/#contact.