How to integrate Penpot with your developer toolchain: APIs and webhooks for workflow automation
Turn design updates into automated workflows. Learn how to connect Penpot with GitHub Actions, GitLab CI/CD, Slack, and custom scripts using APIs, access tokens, and webhooks.
Development tooling works best when every part of the stack is connected and operating as one integrated system. Your design platform should be no exception. Yet many teams still spend hours manually exporting assets and sending design files and updates via Slack or email.
Instead of treating design as a separate workflow full of manual handoffs, it should work as part of your development infrastructure — automated, synchronized, and always up to date.
Penpot was built with this integration-first philosophy. Using its APIs, access tokens, and webhooks, you can connect Penpot directly to tools like GitHub Actions, GitLab CI/CD, Slack, or your own automation scripts. That way, design changes integrate directly into your existing processes — without manual steps or context switching.
In this article, we’ll explore how to integrate Penpot into your developer toolchain using APIs and webhooks and how this automation can eliminate repetitive work while keeping your design and development synchronized across teams.
What are the benefits of integrating Penpot with your developer toolchain?
Manual design-to-development workflows create friction. For example, say a designer updates 10 component colors on Monday, but the developer doesn't find out until Wednesday's standup. Implementation starts on Thursday, and staging deployment happens on Friday. That’s five days from design change to deployed update — when everything goes smoothly.
Penpot integrations collapse these timelines. The same component updates can trigger a webhook the moment the designer saves it, which then exports the design tokens, commits them to your repository, and deploys to staging within minutes.
The practical benefits show up immediately:
- Eliminated manual exports: No more remembering to export assets or running export scripts manually. Scheduled automation or webhook-triggered exports handle it automatically.
- Synchronized design systems: Design tokens in Penpot can stay aligned with the tokens in your codebase when you set up automated sync. When designers update tokens, your pipeline can update code tokens automatically.
- Faster feedback loops: Designers can see their changes in working staging environments within minutes instead of days. This accelerates iteration and catches implementation issues earlier.
- Reduced coordination overhead: Slack messages saying "I updated the designs" become unnecessary. Automated notifications tell the right people exactly what changed and where to find it.
Integrated workflows eliminate the lag between design and delivery, turning your design system into a living part of your development process.
Penpot APIs for extending workflows
Penpot provides an internal RPC-style API that developers can access programmatically using personal access tokens. This API gives you access to projects, files, components, assets, and design data within your workspaces, making it possible to build integrations that sync design data with your codebase or infrastructure.
To generate a token in Penpot, navigate to Your account > Access tokens. Give it a name like "github-actions-export" and set an expiration date (anywhere from 30 days to never). Copy the token and use it in your API requests. Check Penpot’s API documentation to find a list of all available commands.
Now that you know how to generate a token, here are a few ways the Penpot API can help your team.
Retrieve project data and design tokens
With the Penpot API, you can fetch data from projects and workspaces, including component details, typography, and color tokens. For example, you can automatically pull updated token sets into your design system repository, ensuring your UI variables are always current.
Here’s a practical example: Imagine you maintain a documentation site. You can build a Node.js script that calls the API, extracts color tokens and typography definitions, and automatically generates markdown documentation. Schedule it to run nightly with GitHub Actions or a cron job.
const response = await fetch('https://design.penpot.app/api/rpc/command/get-file', {
method: 'POST',
headers: {
'Authorization': 'Token AbCd1234XyZ...',
'Content-Type': 'application/json'
},
body: JSON.stringify({ id: 'file-id-here' })
});
const fileData = await response.json();
When designers update token values in Penpot, your nightly build regenerates documentation automatically. Developers always see current specifications without manual documentation updates.
Automate exports to repos and CI/CD pipelines
Manually exporting design assets and committing them to version control is one of the most repetitive parts of the handoff process. Automating it ensures your development environment always has the latest designs without anyone needing to remember to click “Export.”
Here’s how a typical setup works:
A scheduled GitHub Actions workflow calls the Penpot API to export SVG icons from your design library, commits any updates to your repository, and triggers your build pipeline to deploy the new assets.
The workflow looks like this:
- Trigger – GitHub Actions starts on a schedule (e.g., nightly) or via a webhook dispatch.
- Authenticate – The script uses a Penpot access token stored in GitHub Secrets.
- Export – The script calls the API to export specific artboards or files (for example, SVG icons or components).
- Commit – The files are saved and committed to your repo with a timestamped message, e.g., Auto-export from Penpot [timestamp].
- Deploy – The push automatically triggers your CI/CD pipeline, updating your live environment with the latest assets.
The result: Design updates become deployable code automatically. Designers work in Penpot as usual, while automation handles export, commit, and deployment behind the scenes. Every code review now includes visual diffs for design asset changes, just like any other part of the codebase.
Keep in mind that this requires custom scripting to parse Penpot's API responses and transform them into your desired output formats. The penpot-export tool can handle some of this for design tokens specifically, but for broader asset export workflows, you'll likely need to write your own integration logic.
Sync assets directly with development tools
Penpot’s asset library can be connected with tools like Storybook or component documentation sites through custom automation. This ensures that the icons, illustrations, or UI components developers see in code are the same ones defined in Penpot. No more manual downloads or mismatched versions.
Because Penpot uses open formats like SVG and JSON, integrating these assets is straightforward — no proprietary SDKs or complex conversion needed.
Extending Penpot functionality with MCP servers
Penpot's API flexibility lets you extend capabilities beyond standard features. For instance, developers can build Model Context Protocol (MCP) servers that expose Penpot data to AI tools. Or use Penpot's official MCP server, enabling AI assistants like Claude to interact with design files directly.
Penpot webhooks for real-time automation
While APIs let you pull data from Penpot, webhooks let Penpot push updates to your system. Webhooks send real-time notifications whenever something changes, so your systems can react immediately.
Here are a few ways you could use webhooks to improve your systems.
Trigger Slack or email notifications on updates
Build a simple webhook receiver that posts to Slack when designers update important files. Your endpoint receives the webhook POST request, checks the file ID against a list of important files, and sends a formatted Slack message if it matches.
app.post('/penpot-webhook', async (req, res) => {
const {name, 'file-id': fileId } = req.body;
if (name === 'file-updated' && importantFiles.includes(fileId)) {
await slackClient.chat.postMessage({
channel: '#design-updates',
text: `Design system file updated in Penpot\nView file: https://design.penpot.app/#/workspace/${fileId}`
});
}
res.status(200).send('OK');
});
Deploy this endpoint on your server and add the URL as a webhook in Penpot. When designers save updates to tracked files, your team sees Slack notifications within seconds. Developers know immediately when designs change instead of discovering updates during implementation.
Email notifications work the same way — receive webhook, check criteria, send formatted email to relevant team members.
Create GitHub or GitLab issues automatically
Wire webhooks to your issue tracker to create implementation tickets automatically. When a designer marks a prototype as complete (perhaps by moving it to a specific page or adding a specific comment), a webhook triggers, and your endpoint creates a corresponding GitHub issue.
This eliminates manual ticket creation and ensures every completed design has a corresponding implementation task. Issues get created automatically, assigned to appropriate teams, and linked to the design files.
Push changes into build pipelines instantly
Webhooks can trigger CI/CD actions. For example, when a design token changes, your GitHub Actions workflow listens for this dispatch event, calls the Penpot API to export assets, commits changes, and deploys. In this kind of setup, designers can often see their updates in staging environments within minutes, creating tighter feedback loops that help accelerate iteration.
Best practices for building integrations with Penpot
To get the most value from automation, start small and iterate. Here are some best practices for designing reliable, maintainable integrations:
Secure your access tokens properly
Access tokens are equivalent to passwords. Never commit them to repositories or log them in plain text. Use environment variables for local development and secrets management systems (GitHub Secrets, AWS Secrets Manager, HashiCorp Vault) for production.
Create separate tokens for different integrations. Use github-actions-export for your export automation, slack-notifier for notification endpoints, and docs-generator for documentation scripts. This lets you revoke specific tokens without breaking other integrations and provides better audit trails.
Set reasonable expiration dates. Use 30-day tokens for experimental integrations. Use 90-day tokens for production automation, where you can handle renewal. Avoid "never expires" unless absolutely necessary and implement monitoring to alert before production tokens expire.
Make webhook endpoints idempotent
Webhooks may fire multiple times for the same event due to network retries or how webhook delivery is implemented. Your endpoint must handle duplicate events gracefully without creating duplicate side effects.
Track processed event IDs in a database or cache. Check this before performing actions to prevent duplicate Slack messages, GitHub issues, and builds from repeated webhook deliveries.
Implement comprehensive error handling
Even reliable integrations can fail due to network issues, API limits, malformed payloads, or third-party outages. Your integrations should retry transient failures automatically and alert the team when problems persist.
Log enough context to make debugging straightforward, and monitor error rates so you can spot unusual patterns early. For example, log the file ID, API endpoint, and HTTP status code whenever an export or webhook call fails. You can then visualize these metrics in tools like Grafana or Datadog to quickly spot spikes in failed requests or slow response times.
Document your integrations clearly
Future team members need to understand and maintain integrations without reverse-engineering undocumented code. Create documentation that explains:
- What the integration does and why it exists
- What events trigger it, or what schedule it runs on
- What actions it performs and what external systems it touches
- What credentials it requires, and where they're stored
- How to test it and how to troubleshoot common issues
Use descriptive names everywhere. Call your token github-export-automation-prod instead of token-1. Name webhook endpoints clearly: /webhooks/penpot/design-system-updates instead of /webhook. Structure integration code with the same rigor as application code — use clear functions, comprehensive tests, and maintainable architecture.
Test integrations thoroughly before production
Build integrations against test Penpot projects first. Create a dedicated test team and files specifically for integration development. Then test webhook receivers using Webhook.site to understand payloads before writing production code. Verify that API calls work correctly with sample data before running them against production files.
Use separate tokens for development and production and test that your automation handles edge cases: files with no tokens, empty pages, network timeouts, or API errors. Verify idempotency by sending duplicate webhooks and confirming your endpoint doesn't duplicate work.
When you deploy to production, monitor closely for the first few days. Watch logs for errors, verify automated tasks complete successfully, and confirm side effects happen as expected (Slack notifications are sent, GitHub issues are created, and builds are triggered).
Unlock a design platform where devs feel at home
Penpot’s open-source foundation makes it uniquely suited for automation. With open APIs, flexible webhooks, and file formats based on web standards, you can extend Penpot to fit your exact workflow.
Whether you’re syncing tokens to your codebase, triggering builds on design updates, or delivering instant notifications to your team, Penpot gives you the freedom to integrate design directly into your toolchain.
Ready to integrate Penpot into your development workflow? Explore Penpot's integration capabilities or talk to a Penpot Sales team to see how teams are integrating design directly into their development infrastructure with Penpot.
Related blogs
Want to learn more about integrations and infrastructure in Penpot? Here are more articles:
Yamila Moreno
Yamila Moreno
