Webhooks

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

Navigate to your Studio template's playground and go to the Webhooks tab. Click Add New to create a webhook.

Configure the following options:

2. Get Your Webhook URL

After creating the webhook, copy the Webhook URL:

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, 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, and any service using standard SHA256 HMAC signatures.

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:

{
  "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):

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

Base64 Response:

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

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:

{
  "data": [
    {
      "page": 1,
      "content": "https://storage.orshot.com/cloud/w-123/renders/images/page1.png"
    },
    {
      "page": 2,
      "content": "https://storage.orshot.com/cloud/w-123/renders/images/page2.png"
    },
    {
      "page": 3,
      "content": "https://storage.orshot.com/cloud/w-123/renders/images/page3.png"
    }
  ],
  "format": "png",
  "type": "url",
  "responseTime": "3456.78ms",
  "totalPages": 3,
  "renderedPages": 3
}

Base64 Response:

{
  "data": [
    { "page": 1, "content": "data:image/png;base64,iVBORw0KGgo..." },
    { "page": 2, "content": "data:image/png;base64,iVBORw0KGgo..." },
    { "page": 3, "content": "data:image/png;base64,iVBORw0KGgo..." }
  ],
  "format": "png",
  "type": "base64",
  "responseTime": "3456.78ms",
  "totalPages": 3,
  "renderedPages": 3
}

PDF Response

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

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

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

Need Help?

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