Webhooks

InstaWP let you send real-time site events from your InstaWP account to an external URL through webhooks. This helps developers, agencies, and teams connect InstaWP with their own tools, automation systems, CRMs, Slack channels, project management apps, and custom workflows.

Supported Events

InstaWP currently supports the following webhook events:

Event	Description
Site Created (site.create)	Fires when a new site is created in your InstaWP account.
Site Deleted (site.delete)	Fires when a site is deleted from your InstaWP account.

In this documentation, we will explore the steps to:

• How to Create a Webhook
• Viewing and Managing Webhooks
• What the Incoming Webhook Looks Like
• Common Use Cases

Let’s get started 🚀

How to Create a Webhook

Step 1: Open Webhooks

Sign in to your InstaWP account to access the main dashboard. Go to Settings from the left menu and select Webhooks.

Click on the Create Webhook button. A new window will appear where you can configure your webhook.

Step 2: Choose the events you want to listen to

In this step, you can select the InstaWP events that should trigger the webhook. The available events include: site.create and site.delete.

You can select a single event or multiple events based on your workflow. You can also use the Select all events option to subscribe the webhook to all available events.

👉 Note: A webhook will only trigger for the events selected during setup.

Step 3: Configure your webhook

This window allows you to configure where InstaWP should send the webhook request when the selected event occurs.

You can configure the following values:

| Value | Description | | Destination Name | Add a name for your webhook so you can identify it later. | | Endpoint URL | Add the external URL where InstaWP should send the webhook request. | | Request Type | Select the request format. In the current setup, JSON is used. | | Secret Key | Optional field used to verify webhook requests. | | Description | Optional note to describe what this webhook is used for. |

👉 Note: The endpoint URL should be publicly accessible so InstaWP can send event data to it.

Once all the details have been entered, click Continue.

Step 4: Review and Create

The final screen shows a summary of your configuration:

• Selected events
• Destination name and endpoint URL
• Request type
• Secret key status (set or not set)
• Description

Verify everything is correct, then click Create destination.

You will see a confirmation message: Webhook created successfully. Your webhook now appears in the Webhooks list.

Viewing and Managing Webhooks

Webhooks List

After creating a webhook, go to Settings → Webhooks to see all your webhooks. The list shows:

Column	What It Shows
Name	The webhook name and its endpoint URL.
Status	Whether the webhook is currently active.
Listening To	How many events the webhook is subscribed to.
Activity	A summary of recent webhook activity.
Response Time	Average time your endpoint takes to respond.
Error Rate	Percentage of failed deliveries.
Actions	Options to edit, disable, or delete the webhook.

Webhook Details

Click any webhook in the list to open its detail view. You will see two tabs: ➡ Overview ➡ Event Deliveries

Overview 

Displays the webhook’s configuration and performance metrics at a glance:

• Webhook status (active or inactive)
• Destination URL and selected events
• Total deliveries and error rate (e.g., 0%)
• Average response time (e.g., ~640 ms)
• Charts showing event delivery trends and response times over time

Event Deliveries 

Shows a detailed log of every delivery attempt. Each row includes:

Field	What It Shows
Event	Which event triggered this delivery (e.g., Site Created).
Status	Whether the delivery succeeded or failed.
Attempts	How many times InstaWP tried to deliver this event.
Response Time	How long your endpoint took to respond.
HTTP Status	The HTTP response code returned by your endpoint.
Timestamp	The exact date and time the delivery was made.

What the Incoming Webhook Looks Like

InstaWP sends a POST request to your endpoint with a JSON body. The same envelope is used for every event — event tells you which one fired, and data carries the details.

Request Headers

Header	Description
Content-Type	application/json
User-Agent	InstaWP-Webhooks/1.0
X-InstaWP-Event	The event name, e.g. site.create.
X-InstaWP-Webhook-Id	ID of the webhook destination that sent the request.
X-InstaWP-Delivery-Id	ID of this specific delivery attempt record.
X-InstaWP-Timestamp	Unix timestamp of when the request was signed.
X-InstaWP-Idempotency-Key	Stable key for the event, e.g. site.create:<event_id>. Retries reuse the same key, so use it to de-duplicate.
X-InstaWP-Signature	HMAC-SHA256 signature. Sent only when a secret key is set on the webhook.

Example: Site Created (site.create)

{
  "event_id": "0f2b9c8e-4a71-4d6f-9c33-1a5e7b2d84c1",
  "event": "site.create",
  "version": "1.0",
  "triggered_at": "2026-02-18T09:41:07+00:00",
  "data": {
    "site": {
      "id": 1284392,
      "uuid": "8d3f1a52-77b0-4f9e-a1c4-6be2f0d9c517",
      "hash": "a1b2c3d4e5f6a7b8",
      "name": "client-demo",
      "sub_domain": "client-demo-3xk9p.instawp.site",
      "url": "https://client-demo-3xk9p.instawp.site",
      "domain_url": "demo.acmeagency.com",
      "magic_login_url": "https://app.instawp.io/wordpress-auto-login?site=a1b2c3d4e5f6a7b8",
      "team_id": 41287,
      "team_name": "Acme Agency",
      "user_id": 90218,
      "user_email": "jane@acmeagency.com",
      "php_version": "8.2",
      "wp_version": "6.7.1",
      "status": 1,
      "is_reserved": false,
      "is_template_site": false,
      "source": "dashboard",
      "created_at": "2026-02-18T09:41:05+00:00",
      "updated_at": "2026-02-18T09:41:06+00:00",
      "deleted_at": null
    },
    "user": {
      "id": 90218,
      "name": "Jane Doe",
      "email": "jane@acmeagency.com"
    },
    "customer": null
  }
}

Example: Site Deleted (site.delete)

The body is identical in shape — only event and the timestamps change:

{
  "event_id": "5c71e0a9-32d4-4f18-8b60-9d0c4e7a1f22",
  "event": "site.delete",
  "version": "1.0",
  "triggered_at": "2026-02-19T14:02:33+00:00",
  "data": {
    "site": {
      "id": 1284392,
      "uuid": "8d3f1a52-77b0-4f9e-a1c4-6be2f0d9c517",
      "hash": "a1b2c3d4e5f6a7b8",
      "name": "client-demo",
      "sub_domain": "client-demo-3xk9p.instawp.site",
      "url": "https://client-demo-3xk9p.instawp.site",
      "domain_url": "client-demo-3xk9p.instawp.site",
      "magic_login_url": "https://app.instawp.io/wordpress-auto-login?site=a1b2c3d4e5f6a7b8",
      "team_id": 41287,
      "team_name": "Acme Agency",
      "user_id": 90218,
      "user_email": "jane@acmeagency.com",
      "php_version": "8.2",
      "wp_version": "6.7.1",
      "status": 0,
      "is_reserved": false,
      "is_template_site": false,
      "source": "dashboard",
      "created_at": "2026-02-18T09:41:05+00:00",
      "updated_at": "2026-02-19T14:02:31+00:00",
      "deleted_at": "2026-02-19T14:02:32+00:00"
    },
    "user": {
      "id": 90218,
      "name": "Jane Doe",
      "email": "jane@acmeagency.com"
    },
    "customer": null
  }
}

The customer Object (Demo Sites)

customer is null for regular sites. When the site was created as a demo site from a shared snapshot, it carries the details the visitor entered on the demo form:

"customer": {
  "email": "visitor@example.com",
  "name": "Alex Visitor",
  "marketing_optin": "Enabled"
}

Fields fall back to "NA" when the visitor did not provide them, and marketing_optin is either "Enabled" or "NA".

Field Reference

Field	Description
event_id	Unique ID for this event.
event	The event name: site.create or site.delete.
version	Payload schema version (currently 1.0).
triggered_at	ISO 8601 timestamp of when the event fired.
data.site	The site the event is about — IDs, URLs, PHP/WP versions, status and timestamps.
data.site.hash	Site hash, also used in the magic login URL.
data.site.domain_url	The mapped custom domain (hostname only). Falls back to the InstaWP subdomain when no domain is mapped.
data.site.magic_login_url	One-click auto-login link into wp-admin. Treat it as a credential.
data.user	The InstaWP account owner the site belongs to.
data.customer	Demo-site visitor details, or null for regular sites.

Verifying the Signature

If you set a Secret Key on the webhook, InstaWP signs each request. The signature is an HMAC-SHA256 of the X-InstaWP-Timestamp value, a literal dot, and the raw request body, using your secret key as the HMAC key:

signature = HMAC_SHA256(secret_key, timestamp + "." + raw_body)

PHP example:

$timestamp = $_SERVER['HTTP_X_INSTAWP_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_INSTAWP_SIGNATURE'] ?? '';
$rawBody   = file_get_contents('php://input');

$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secretKey);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

Node.js example:

const crypto = require('crypto');

const expected = crypto
  .createHmac('sha256', secretKey)
  .update(`${req.headers['x-instawp-timestamp']}.${rawBody}`)
  .digest('hex');

const ok = crypto.timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(req.headers['x-instawp-signature'] || '')
);

👉 Note: Sign the raw request body exactly as received. Re-encoding the JSON changes the bytes and the signature will not match.

Responding to a Webhook

Return any 2xx status code to acknowledge the delivery. Anything else counts as a failure.

• InstaWP retries a failed delivery up to 3 times, waiting 1 minute after the first failure and 5 minutes after the second.
• Retries reuse the same X-InstaWP-Idempotency-Key, so make your handler idempotent.
• A webhook that keeps failing is automatically disabled, and you will see the attempts under Event Deliveries.

Common Use Cases

1. Team Notifications

Send a Slack or Discord message whenever a new staging site is created or deleted. This keeps your agency, dev team, or support team informed without manual follow-ups.

2. CRM Updates

When a demo site is created, automatically update the lead record in HubSpot, Pipedrive, Airtable, or your internal CRM. Useful for demo tracking, lead management, and WaaS sales funnels.

3. Project Management Automation

Automatically create a QA task in ClickUp, Asana, Trello, Jira, or Linear when a new site is built. This ensures every client build goes through your standard checklist.

4. WaaS and Demo Site Automation

When a user creates a demo site from a template, trigger onboarding emails, start a trial timer, and update the customer record—all automatically.

5. Site Cleanup Workflows

When a temporary demo site is deleted, mark the demo as expired in your CRM and clean up related records. Keeps your external systems in sync.

6. Developer CI/CD Triggers

Trigger a custom script after site creation that installs a plugin build, runs automated tests, or updates an internal system. Useful for plugin/theme developers and QA teams.

Summary

InstaWP Webhooks help you connect site activity inside InstaWP with the rest of your workflow. You can use webhooks to trigger automations when a site is created or deleted, notify your team, update your CRM, start WaaS workflows, create project tasks, or clean up external records.

💡 Did you know: Webhooks are especially useful for agencies and developers managing multiple staging, demo, and client sites because they reduce manual follow-ups and keep external systems updated automatically.

Frequently Asked Questions

What are InstaWP Webhooks?

InstaWP Webhooks are automated HTTP requests sent from InstaWP to an external endpoint when selected site events happen.

Which events are currently supported?

The current webhook flow supports Site Created and Site Deleted events.

Can I select multiple events for one webhook?

Yes. You can select one event, multiple events, or use Select all events.

What request format does InstaWP use for webhooks?

The current setup sends webhook data in JSON format.

Is the secret key required?

No. The secret key is optional, but it is recommended for production workflows.

Where can I see webhook delivery logs?

Open the webhook from the Webhooks list and go to the Event Deliveries section.

Can I test webhooks before using them in production?

Yes. You can use a temporary webhook testing tool such as webhook.site to inspect incoming webhook requests.

Related Articles

• Snapshots Overview - What snapshots are and how they work
• Find Snapshot Slug - Locate the snapshot slug for a webhook
• Create a Site via API - Create sites programmatically
• Using Snapshots (Create Site) - Launch a site from a snapshot