📩Webhooks

Webhooks let DevPayr tap your backend on the shoulder and say, “Hey, something just changed — you may want to react.”

Instead of polling DevPayr for updates, you give us an HTTPS endpoint and we send signed JSON requests whenever important events happen on your projects, licenses, or domains.

Common things you might do with webhooks:

• Activate or lock a user’s account after a license is created or suspended

• Sync project/domain changes into your own admin panel

• Trigger emails or notifications when a project is marked as paid

• Keep your billing system and DevPayr in sync without manual work

1. Where to Configure Webhooks

You can define a webhook endpoint in two places:

a) Account-level webhook (profile / settings)

From your DevPayr dashboard:

• Go to Settings → Account

• Set your Webhook Endpoint — e.g. https://yourapp.com/devpayr/webhooks

This acts as a fallback URL used by all projects that don’t have their own project-level webhook.

b) Project-level webhook

When creating or editing a project (see the “Create New Project” screen):

• In Integration / Webhook Settings, set:

  • Project Webhook URL – where this project’s webhooks should be sent

  • Webhook Secret – a secret string used to sign payloads (more on this below)

If a project has its own Project Webhook URL, that URL is used instead of the profile-level one.

Rule of thumb

• Project Webhook URL set? → use that

• Otherwise → use profile-level webhook URL

• If neither exists → no webhooks are sent for that project

2. Events DevPayr Sends

DevPayr sends webhooks for changes around projects, domains, and licenses.

Each webhook payload has this general structure:

{
  "event": "event.name.here",
  "data": {
    // event-specific fields
  }
}

And every request includes helpful HTTP headers (explained in the next section).

Project-level events

These events help you keep your own system in sync with what’s happening to a project.

• project.created Fired when a new project is created in DevPayr.

• project.updated Fired when key project fields change (name, slug, description, logo, redirect URL, meta, etc.).

• project.paid_status_toggled Fired whenever the has_paid flag on a project is turned on or off. Useful if you treat “has_paid = false” as “lock this product”.

Project domain events

These events are about domains attached to a project.

• project.domain.added A domain has been added to the project (including environment, whether it’s primary, verified, etc.).

• project.domain.deleted A domain has been removed from the project.

• project.domain.environment_updated The domain’s environment changed (e.g., from staging to production).

• project.domain.primary_set A domain has been set as the primary domain for the project.

License events

These events track the lifecycle of a license and the domains attached to it.

• license.created A new license was created for a project.

• license.suspended A license was suspended / revoked (you’ll usually want to lock the user here).

• license.reactivated A previously suspended license is re-enabled.

• license.domain.added A new domain has been attached/learned for that license (license-level domain mode).

• license.domain.removed A domain has been detached from that license.

You don’t need to memorize all of these — your endpoint will always receive the event name in the payload and in a header so you can switch on it.

3. Request Format & Headers

Every webhook delivery is:

• An HTTP POST

• With Content-Type: application/json

• Carrying the JSON payload described above

In addition, DevPayr includes a few headers to help you route and verify the request:

• X-Webhook-Event – the event name (e.g. license.created)

• X-Project-ID – the numeric ID of the project firing the event

• X-License-ID – present for license-related events (license created / suspended / etc.)

• X-Signature – HMAC-SHA256 signature of the JSON payload using your project’s Webhook Secret

Tip

If you don’t set a Webhook Secret on the project, X-Signature will be empty. For production systems, always set a secret and verify every request.

4. Example Payloads

These examples show the shape of the data you’ll receive. Field names may grow over time, but the structure remains similar.

4.1 project.created

{
  "event": "project.created",
  "data": {
    "id": 42,
    "name": "NextroPay",
    "slug": "nextropay-app",
    "description": "Billing dashboard for clients",
    "default_redirect_url": "https://nextropay.com/block",
    "logo_url": "https://cdn.devpayr.com/projects/42/logo.png",
    "meta": {
      "client_id": "C-10294",
      "internal_note": "Enterprise client"
    },
    "is_active": true,
    "created_at": "2025-12-08T12:30:15Z"
  }
}

You can use this to auto-create a matching record in your own database.

4.2 project.paid_status_toggled

{
  "event": "project.paid_status_toggled",
  "data": {
    "id": 42,
    "has_paid": true,
    "updated_at": "2025-12-08T13:02:44Z"
  }
}

Typical reaction in your system:

• has_paid = true → unlock the software, enable premium features

• has_paid = false → schedule a downgrade, show a “payment required” message, etc.

4.3 license.created

{
  "event": "license.created",
  "data": {
    "license_id": 1205,
    "license_uuid": "019ae895-bbdf-70a2-b615-1a5d396e8ef6",
    "title": "Premium Web License",
    "is_test_license": false,
    "allow_configs": true,
    "max_domains": 3,
    "max_usage_per_day": 1000,
    "project_id": 42,
    "created_at": "2025-12-08T13:15:00Z"
  }
}

You might:

• Attach this license to the customer record in your own DB

• Trigger a “Your license is ready” email with the masked key

• Start a provisioning job for the customer’s environment

4.4 license.suspended

{
  "event": "license.suspended",
  "data": {
    "license_id": 1205,
    "license_uuid": "019ae895-bbdf-70a2-b615-1a5d396e8ef6",
    "title": "Premium Web License",
    "project_id": 42,
    "suspended_at": "2025-12-08T14:05:10Z"
  }
}

Typical reactions:

• Mark the customer’s subscription as “suspended”

• Lock logins or reduce features in your app

• Show an in-app banner telling them to contact billing or renew

4.5 project.domain.added

{
  "event": "project.domain.added",
  "data": {
    "id": 88,
    "domain": "myclient.com",
    "environment": "production",
    "is_primary": true,
    "is_verified": true,
    "is_locked": false,
    "project_id": 42,
    "created_at": "2025-12-08T13:30:00Z"
  }
}

You could:

• Log this domain in your control panel

• Use it to configure routing, SSL, or DNS automation in your own infra

4.6 license.domain.added

{
  "event": "license.domain.added",
  "data": {
    "id": 301,
    "domain": "store.myclient.com",
    "project_id": 42,
    "license_id": 1205,
    "subdomain_count": 2,
    "added_at": "2025-12-08T15:00:00Z"
  }
}

If you use DevPayr’s license-level domain tracking, this lets you see where a license is being activated.

5. Verifying the Signature

To make sure a webhook really came from DevPayr and not from a random script, you should verify the X-Signature header using your Webhook Secret.

The logic is:

1. Take the raw JSON body exactly as received.

2. Compute HMAC-SHA256(body, webhook_secret)

3. Compare that value to the X-Signature header (constant-time compare if possible).

4. If they don’t match, reject the request.

Example – Node.js (Express)

import crypto from "crypto";
import express from "express";

const app = express();

// Keep raw body for signature verification
app.use(
  express.json({
    verify: (req, _res, buf) => {
      req.rawBody = buf.toString("utf8");
    },
  })
);

app.post("/devpayr/webhooks", (req, res) => {
  const signature = req.header("X-Signature") || "";
  const secret = process.env.DEVPAYR_WEBHOOK_SECRET || "";

  const computed = crypto
    .createHmac("sha256", secret)
    .update(req.rawBody)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(computed))) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body.event;
  const data = req.body.data;

  // Handle events here...
  console.log("✅ Valid DevPayr webhook:", event, data);

  res.status(200).send("ok");
});

Example – PHP (generic)

<?php

$secret = getenv('DEVPAYR_WEBHOOK_SECRET') ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

$rawBody = file_get_contents('php://input');

$computed = hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($signature, $computed)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
$event = $payload['event'] ?? null;
$data  = $payload['data'] ?? [];

switch ($event) {
    case 'license.created':
        // handle new license
        break;

    case 'license.suspended':
        // handle suspension
        break;

    // ...
}

http_response_code(200);
echo 'ok';

You can adapt the same pattern in any language that supports HMAC-SHA256.

Tip

Always respond quickly (just 200 OK) and push heavy work (emails, database tasks, external API calls) to a background job or queue. Webhooks should be treated like fire alarms — acknowledge fast, handle details in the background.

6. Best Practices

To get the most out of DevPayr webhooks:

• Always use HTTPS for your webhook endpoint.

• Set a Webhook Secret for each project and verify X-Signature on every request.

• Use project-level webhooks when different projects need to hit different systems.

• Log incoming webhooks on your side while integrating — it makes debugging far easier.

• Make processing idempotent (don’t double-process the same event if your endpoint is called twice). Using a combination of event + resource ID + timestamp is usually enough.

• Return a 2xx status code once you’ve accepted the event. Non-2xx means “delivery failed”.

Once your webhook endpoint is wired up, DevPayr becomes much more than “just a license check”. Your own systems will be able to react in real-time whenever licenses, domains, or project billing status change — without you writing extra cron jobs or manual sync scripts.