Webhooks

Get notified in real-time when things happen in your workspace.

Overview

Webhooks send HTTP POST requests to your server when events occur in GoPimi — tickets created, conversations updated, contacts changed, SLA breached. Each workspace can have multiple webhooks, each subscribed to specific event types.

Setting Up a Webhook

1. Go to Settings → Webhooks in your workspace
2. Click Add Webhook
3. Enter your endpoint URL (must be HTTPS)
4. Select the events you want to receive
5. Save — GoPimi generates a signing secret for verification

You can also manage webhooks via the API:

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/gopimi",
    "events": ["ticket.created", "ticket.updated"]
  }' \
  /api/v1/workspaces/WORKSPACE_ID/webhooks

Event Types

15 event types across tickets, conversations, contacts, and SLA:

Payload Format

Every webhook delivery sends a JSON payload:

{
  "event": "ticket.created",
  "timestamp": "2026-03-26T14:30:00Z",
  "workspace_id": 1,
  "data": {
    "id": 42,
    "subject": "Ticket #42 - Cannot access dashboard",
    "status": "open",
    "contact": { "id": 5, "name": "Jane Doe", "email": "[email protected]" },
    "agent": null,
    "created_at": "2026-03-26T14:30:00Z"
  }
}

Verifying Signatures

Every delivery includes an X-GoPimi-Signature header — an HMAC-SHA256 hash of the request body using your webhook's signing secret. Always verify this to ensure the request came from GoPimi.

// PHP example
$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $webhookSecret);

if (!hash_equals($signature, $_SERVER['HTTP_X_GOPIMI_SIGNATURE'])) {
    http_response_code(401);
    exit('Invalid signature');
}

// Node.js example
const crypto = require('crypto');

const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(requestBody)
  .digest('hex');

if (signature !== req.headers['x-gopimi-signature']) {
  return res.status(401).send('Invalid signature');
}

Retry Behavior

If your endpoint returns a non-2xx status or times out:

• GoPimi retries with exponential backoff
• Each delivery attempt is logged with status code and response body
• View delivery logs in Settings → Webhooks → [webhook] → Deliveries

Quotas

The number of webhooks per workspace is governed by your plan's resource quotas. Check Settings → Usage to see your current limits.

Frequently Asked Questions

How are webhook payloads signed?

Using HMAC-SHA256 of the full JSON body with the webhook's per-webhook secret, sent in the X-GoPimi-Signature header. Verify this on your endpoint before trusting the payload.

How many times will a failed delivery retry?

Up to five times with exponential backoff. Every attempt is recorded in webhook_deliveries with HTTP status, response body, and timing.

Which HTTP status codes count as a successful delivery?

Any 2xx response. 3xx, 4xx, and 5xx responses trigger retry.

Where can I inspect past deliveries?

Call GET /workspaces/{id}/webhooks/{webhook}/deliveries to see every delivery attempt for a given webhook, with status, response, and timing.

Related

• Email Pipeline — How inbound emails trigger ticket/conversation creation
• SLA Policies — Configure the deadlines that trigger SLA breach events
• API Reference — Webhook CRUD endpoints