Webhooks

Webhooks send NOCK ticket events to HTTPS endpoints you control. Use them to update a CRM, notify Slack, trigger an n8n workflow, feed your own backend, or power external adapters for GitHub Issues and Jira.

Create webhooks in the dashboard

Workspace admins can create webhook endpoints from the workspace integrations area:

Webhook URLs must use HTTPS. Local, private, loopback, and internal network hosts are rejected to reduce SSRF risk.

Manage webhooks by API

API keys need webhooks:write.

List endpoints:

curl -sS "https://nocknock.cloud/api/v1/webhooks" \
  -H "Authorization: Bearer $NOCK_API_KEY"

Create an endpoint:

curl -sS -X POST "https://nocknock.cloud/api/v1/webhooks" \
  -H "Authorization: Bearer $NOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/nock/webhook",
    "project_id": "'"$NOCK_PROJECT_ID"'",
    "events": ["ticket.created", "ticket.status_changed"]
  }'

Disable an endpoint:

curl -sS -X DELETE "https://nocknock.cloud/api/v1/webhooks/$NOCK_WEBHOOK_ID" \
  -H "Authorization: Bearer $NOCK_API_KEY"

Project-scoped API keys can manage only webhooks for their project.

Events

When a status changes, NOCK sends both ticket.updated and ticket.status_changed. Use idempotency in your consumer if both events can trigger the same downstream action.

Dashboard test deliveries use webhook.test. This event is not selectable as a subscription event; it is emitted only when a workspace admin manually tests an endpoint.

Payload shape

{
  "id": "evt_...",
  "event": "ticket.created",
  "created_at": "2026-06-25T12:00:00.000Z",
  "org_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "00000000-0000-0000-0000-000000000000",
  "ticket_id": "00000000-0000-0000-0000-000000000000",
  "ticket_reference": "NK-1234",
  "data": {
    "ticket": {
      "id": "00000000-0000-0000-0000-000000000000",
      "title": "Checkout fails on Safari",
      "status": "Backlog",
      "priority": "normal",
      "source": "widget",
      "annotations": [
        {
          "type": "pin",
          "page_url": "https://example.com/checkout",
          "x": 640,
          "y": 360,
          "x_ratio": 0.5,
          "y_ratio": 0.4,
          "selector": "#pay-button",
          "screenshot_image_id": "00000000-0000-0000-0000-000000000000"
        },
        {
          "type": "text_edit",
          "page_url": "https://example.com/checkout",
          "selector": "#headline",
          "original_text": "Old headline",
          "suggested_text": "New headline",
          "comment": "Use clearer checkout copy"
        }
      ]
    }
  }
}

ticket_reference is NOCK's human-readable ticket reference (NK-XXXX), derived deterministically from the ticket ID. It is sent on ticket events but omitted from webhook.test deliveries (which carry no ticket), so treat it as optional in your consumer. NOCK does not send the Linear issue identifier in webhook payloads, even for Linear-synced tickets — correlate on ticket_id instead.

Widget-created tickets can include data.ticket.annotations. Pin annotations include page, viewport, selector or nearby text, coordinates, and may include screenshot_image_id. Webhook payloads intentionally omit attachment bytes and screenshot_url; retrieve current attachment URLs through the authenticated Ticket API. Text-edit annotations include selector context, original_text, suggested_text, and optional comments.

For ticket.note.created, data also includes a note object. Internal notes are not emitted as ticket.note.created; only customer-visible replies are sent to external webhook consumers.

Headers

NOCK sends:

Always verify the signature before performing side effects.