---
canonical: 'https://htmlcsstoimage.com/features/webhooks'
title: 'Image API Webhooks: Stored, Deleted, and Updated Events | HTML/CSS to Image'
description: 'Receive signed webhook deliveries when images are stored or deleted, templates and storage destinations change, or usage alerts fire. Automatic retries, custom headers, and delivery history included.'
---

# Know the moment an image lands in storage

Subscribe an HTTPS endpoint to the events you care about. HTML/CSS to Image signs every delivery, retries the ones that fail, and keeps a delivery history you can open from the dashboard.

## Key capabilities

- Signed deliveries
- Automatic retries
- Delivery history

## Stop polling for finished images

An HTML/CSS to Image request returns an image URL right away, and the image is rendered the first time something asks for it. Subscribe to `image_stored` and HCTI sends your endpoint an event when the rendered file has been saved, with its size, its dimensions, and where it was stored: HCTI storage or one of your [custom storage destinations](https://htmlcsstoimage.com/features/custom-storage.md). Each storage location gets its own event, so a file written to your S3 or R2 bucket is reported separately from the copy HCTI serves.

That is the signal to publish a post, attach an image to an email, or warm your CDN, without a loop that keeps checking whether the file is there yet. It works the same way for [Open Graph images](https://htmlcsstoimage.com/features/og-images.md) rendered on a visitor's first page view and for [batch requests](https://htmlcsstoimage.com/features/batch-images.md).

## Events you can subscribe to

| Area | Events |
| --- | --- |
| Images | `image_stored`, `image_deleted` (one event per delete request, listing the images it removed) |
| [Templates](https://htmlcsstoimage.com/features/templates.md) | `template_created`, `template_updated`, `template_deleted` |
| Proxies | `proxy_created`, `proxy_updated`, `proxy_deleted` |
| Storage destinations | `storage_destination_created`, `storage_destination_updated`, `storage_destination_deleted` |
| Open Graph configs | `og_config_created`, `og_config_updated`, `og_config_deleted` |
| API keys | `api_key_created`, `api_key_updated`, `api_key_deleted` |
| Organization | `organization_plan_changed`, `organization_usage_reset`, `organization_usage_alert` |

Update events include a `changes` object with each changed property's previous and new value. Secrets such as storage credentials and proxy passwords are reported as set or not set, never as values. Long template HTML and CSS are truncated in the change, and a block template's design is reported as changed without its contents.

A webhook can only subscribe to events its creator is allowed to read: an API key without `usage:read` cannot subscribe to usage alerts.

## Signed, retried, and recorded

- **Signatures.** Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com/) format: `webhook-id`, `webhook-timestamp`, and an HMAC-SHA256 `webhook-signature`, so existing Standard Webhooks libraries can verify them. Copy the signing secret from the dashboard.
- **Retries.** A delivery that times out, can't connect, or gets a 408, 429, or 5xx response is retried up to 5 attempts in total, after 5 minutes, 1 hour, 12 hours, and 2 days. A `Retry-After` header can push the next attempt later. Redirects are not followed.
- **Duplicates are safe to detect.** Retries of the same delivery reuse its `webhook-id`, so your handler can ignore one it has already processed.
- **Delivery history.** The dashboard lists every event with the exact payload that was sent and the status code and timing of each attempt. Filter by webhook to debug one endpoint.

## Send it where your workflow already runs

Point a webhook at your own API, a serverless function, or the catch-hook URL of an [automation tool](https://docs.htmlcsstoimage.com/integrations/) such as Zapier or Make. Add custom headers or query parameters for the receiving system's authentication, and mark them secret so they are encrypted and never shown again. Endpoints must use HTTPS.

Creating a webhook, enabling it, or changing where it delivers sends a `webhook_test` event, and the dashboard has a **Send test** button for checking your handler at any time.

## Manage webhooks through the REST API or MCP

| Operation | REST endpoint | MCP tool | Required permission |
| --- | --- | --- | --- |
| Create | `POST /v1/webhooks` | `create_webhook` | `webhooks:create_update` |
| Update | `POST /v1/webhooks/{id}` | `update_webhook` | `webhooks:create_update` |
| List | `GET /v1/webhooks` | `list_webhooks` | `webhooks:read` |
| Get | `GET /v1/webhooks/{id}` | `get_webhook` | `webhooks:read` |
| Delete | `DELETE /v1/webhooks/{id}` | `delete_webhook` | `webhooks:delete` |
| Send a test event | `POST /v1/webhooks/{id}/test` | `send_webhook_test_event` | `webhooks:create_update` |
| Get a delivered event | `GET /v1/webhooks/events/{id}` | `get_webhook_event` | `webhooks:read` |

Free plans include 2 webhooks per organization and paid plans include 10. See [pricing](https://htmlcsstoimage.com/pricing.md) for plan details, and [security](https://htmlcsstoimage.com/features/security.md) for how API key and MCP permissions work.

## MCP Integration

Connect an MCP-compatible client to `https://mcp.hcti.io` with OAuth. The tools use the connected organization's HTML/CSS to Image account, permissions, and plan limits.

- The `list_webhooks` and `get_webhook` tools return the connected organization's webhooks and their subscribed events. `send_webhook_test_event` queues a test delivery, and `get_webhook_event` returns a delivered event with its payload and delivery attempts.

[Read the full MCP docs](https://docs.htmlcsstoimage.com/integrations/mcp/).

## What teams build with webhooks

### Publish when the file exists

Wait for image_stored before you attach an image to an email, a product listing, or a CMS entry, so nobody ships a link that is still rendering.

### Keep your database in sync

Mirror template, proxy, storage destination, and API key changes into your own records instead of scheduling a job to diff them.

### Clean up after deletes

Remove cached copies and references in your app when image_deleted reports which images a delete request removed.

### Watch usage and billing

Route usage alerts, usage resets, and plan changes to Slack, an incident tool, or the finance team's inbox.

## Related features

- [Custom Storage](https://htmlcsstoimage.com/features/custom-storage.md): Store generated images in your object storage.
- [Open Graph Images](https://htmlcsstoimage.com/features/og-images.md): Fresh preview images from page metadata.
- [Security](https://htmlcsstoimage.com/features/security.md): Options to secure your renders.

## Get started

REST API requests require an HTML/CSS to Image account and should be authenticated from trusted application code. Check the API docs and pricing for current setup instructions, limits, and feature availability.

- [View the full feature page](https://htmlcsstoimage.com/features/webhooks)
- [Browse all features](https://htmlcsstoimage.com/features.md)
- [View pricing](https://htmlcsstoimage.com/pricing.md)
- [Read the webhook docs](https://docs.htmlcsstoimage.com/guides/webhooks/)
- [Read the MCP docs](https://docs.htmlcsstoimage.com/integrations/mcp/)