Webhooks

Trigger image, PDF and video generation from a form, an automation tool, or any HTTP client.

Updated

Webhooks allow you to automatically generate images and PDFs when events occur in external services like Typeform, Tally, Zapier, Make, n8n, or your own backend. Instead of making API calls with an API key, you use a unique webhook URL that handles authentication automatically.

How It Works#

  1. Create a webhook for your Studio template
  2. Configure field mappings to connect incoming data to template modifications
  3. Point your form or service to the webhook URL
  4. When triggered, Orshot generates an image and returns it in your chosen format

Setting Up Webhooks#

1. Create a Webhook#

Open the template's Connect sheet from your dashboard and go to the Webhook tab. Click Add New to create a webhook.

Webhooks are available on paid plans. On the free plan, the Webhook tab shows an upgrade prompt instead.

Configure the following options:

OptionDescription
Webhook NameA friendly name to identify this webhook (e.g., "Tally Form", "Zapier")
Response FormatImage format: PNG, JPG, JPEG, WebP or PDF
Response TypeHow the image is returned: url, base64, or binary
Credit LimitMost credits this webhook can spend (leave empty for unlimited)
Enable Signing SecretTurn on to verify webhook requests are authentic

2. Get Your Webhook URL#

After creating the webhook, copy the Webhook URL:

JavaScript
https://api.orshot.com/v1/studio/webhook/wh_yourWebhookId

Use this URL as the webhook endpoint in your form builder or automation tool.

3. Configure Field Mappings#

Field mappings connect incoming webhook data to your template's dynamic fields.

Auto-detection: Trigger the webhook once from your form or service. Orshot automatically detects available fields from the payload and shows them in the Field Mappings section.

Manual mapping: Select which incoming field maps to each template modification using the dropdowns.

Example mapping:

  • name → page1@heading
  • email → page1@subheading
  • avatar_url → page1@profileImage

Signature Verification#

For production use, turn on Enable Signing Secret to verify that webhook requests actually come from your configured service.

How to Use#

  1. Copy the Signing Secret from your webhook settings in Orshot
  2. Paste it into your form builder's webhook signing configuration
  3. Orshot will reject requests with invalid or missing signatures

Orshot automatically detects and verifies signatures from popular services like Typeform, Tally, GitHub, Stripe, Slack, Shopify and Svix-based senders.

Signing your own requests#

To sign requests from your own backend, compute an HMAC-SHA256 of the raw request body, using the signing secret as the key. Send it in a header whose name contains signature, for example X-Signature. The value can be hex or base64, with or without a sha256= prefix.

JavaScript
import crypto from "node:crypto";

const signingSecret = "YOUR_SIGNING_SECRET";
const body = JSON.stringify({ name: "John Doe" });
const signature = crypto
  .createHmac("sha256", signingSecret)
  .update(body)
  .digest("hex");

await fetch("https://api.orshot.com/v1/studio/webhook/wh_yourWebhookId", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Signature": `sha256=${signature}`,
  },
  body,
});

Sign the exact body you send. If you re-serialize the JSON after signing, the signature will not match.

Usage Examples#

Typeform#

  1. In Typeform, go to Connect → Webhooks
  2. Add your Orshot webhook URL
  3. (Optional) Add the signing secret for verification
  4. Submit a test response to detect fields
  5. Map Typeform fields to template modifications in Orshot

Tally#

  1. In your Tally form, go to Integrations → Webhooks
  2. Paste your Orshot webhook URL
  3. Submit a test response
  4. Configure field mappings in Orshot

Zapier / Make / n8n#

  1. Add a Webhook action in your automation
  2. Set method to POST
  3. Use your Orshot webhook URL
  4. Send a JSON body with your field values:
JSON
{
  "name": "John Doe",
  "title": "Software Engineer",
  "avatar": "https://example.com/photo.jpg"
}

Response#

The webhook returns the generated image based on your configured response type.

Single Page Template#

URL Response (default):

JSON
{
  "data": {
    "content": "https://storage.orshot.com/cloud/w-123/renders/images/abc123.png",
    "type": "url",
    "format": "png",
    "responseTime": 1234.56
  }
}

Base64 Response:

JSON
{
  "data": {
    "content": "data:image/png;base64,iVBORw0KGgo...",
    "type": "base64",
    "format": "png",
    "responseTime": 1234.56
  }
}

Binary Response: Returns the raw image file directly with appropriate content-type headers.

Multi-Page Template#

For multi-page templates, the response includes an array of pages:

URL Response:

JSON
{
  "data": [
    {
      "page": 1,
      "pageId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
      "content": "https://storage.orshot.com/cloud/w-123/renders/images/page1.png"
    },
    {
      "page": 2,
      "pageId": "b2c3d4e5-6f78-9012-bcde-f23456789012",
      "content": "https://storage.orshot.com/cloud/w-123/renders/images/page2.png"
    },
    {
      "page": 3,
      "pageId": "c3d4e5f6-7890-1234-cdef-345678901234",
      "content": "https://storage.orshot.com/cloud/w-123/renders/images/page3.png"
    }
  ],
  "format": "png",
  "type": "url",
  "responseTime": 3456.78,
  "totalPages": 3,
  "renderedPages": 3
}

Base64 Response:

JSON
{
  "data": [
    { "page": 1, "pageId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "content": "data:image/png;base64,iVBORw0KGgo..." },
    { "page": 2, "pageId": "b2c3d4e5-6f78-9012-bcde-f23456789012", "content": "data:image/png;base64,iVBORw0KGgo..." },
    { "page": 3, "pageId": "c3d4e5f6-7890-1234-cdef-345678901234", "content": "data:image/png;base64,iVBORw0KGgo..." }
  ],
  "format": "png",
  "type": "base64",
  "responseTime": 3456.78,
  "totalPages": 3,
  "renderedPages": 3
}

PDF Response#

For PDF format, all pages are merged into a single file:

JSON
{
  "data": {
    "content": "https://storage.orshot.com/cloud/w-123/renders/images/document.pdf",
    "type": "url",
    "format": "pdf",
    "responseTime": 2345.67
  }
}

Managing Webhooks#

  • Enable/Disable: Toggle webhooks on or off without deleting them
  • Reset Secret: Generate a new signing secret (invalidates existing integrations)
  • Clear Fields: Re-detect fields by clearing the stored payload
  • Delete: Remove the webhook entirely

Errors#

StatusErrorWhen
404Webhook not foundThe webhook ID in the URL does not exist
403Webhook is disabledThe webhook is turned off
403Webhook has reached its credit limit (N credits)The webhook has spent its Credit Limit
401Invalid webhook signatureSigning is on and the signature is missing or wrong

Need Help?#

Contact support at hi@orshot.com or use the chat button in your Orshot dashboard for assistance.

Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key
  • Image, PDF and video generation via API
  • Visual editor with AI and smart layouts
  • Zapier, Make, MCP and 40+ integrations
  • White-label embed for your own app
  • 100 free credits a month, no credit card required