PerfectParser Docs
API ReferenceWebhooks

Webhook Endpoints

Reference for Webhooks CRUD API endpoints (List, Create, Get, Update, Delete, and Test subscriptions).

GET /v1/webhooks

Retrieves webhook subscriptions with cursor-based pagination.

Query Parameters

ParameterTypeRequiredDescription
limitinteger❌Results per page (default 20, max 100).
cursorstring❌Pagination cursor from previous response.
curl "https://api.perfectparser.com/v1/webhooks?limit=20" \
  -H "X-API-Key: pp_live_your_secret_key"

Response 200 OK

{
  "webhooks": [
    {
      "webhook_id": "wh_123",
      "url": "https://hooks.zapier.com/...",
      "events": ["extraction.document_completed", "extraction.job_completed"],
      "is_active": true,
      "created_at": "2026-06-20T10:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "has_next_page": false,
    "next_cursor": null
  }
}

POST /v1/webhooks

Creates a new webhook subscription to receive real-time extraction events.

The response includes signing_secret once. Store it immediately — it cannot be retrieved again. Use it to verify X-PerfectParser-Signature HMAC on incoming payloads.

Body Parameters

ParameterTypeRequiredDescription
urlstring✅Callback HTTP POST URL (HTTPS required in production).
eventsstring[]✅extraction.document_completed, extraction.job_completed.
secretstring❌Optional static token (min 8 chars) sent as X-Webhook-Secret. Useful for Zapier/Make.
curl -X POST https://api.perfectparser.com/v1/webhooks \
  -H "X-API-Key: pp_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://my-server.com/callback", "events": ["extraction.job_completed"], "secret": "my_shared_token"}'

Response 201 Created

{
  "webhook": {
    "webhook_id": "wh_123",
    "url": "https://my-server.com/callback",
    "events": ["extraction.job_completed"],
    "is_active": true,
    "created_at": "2026-06-20T10:00:00.000Z",
    "signing_secret": "wh_sec_a1b2c3d4..."
  }
}

GET /v1/webhooks/:id

Retrieves configuration details and the last 10 delivery attempts.

curl https://api.perfectparser.com/v1/webhooks/wh_123 \
  -H "X-API-Key: pp_live_your_secret_key"

Response 200 OK

{
  "webhook": {
    "webhook_id": "wh_123",
    "url": "https://my-server.com/callback",
    "events": ["extraction.document_completed", "extraction.job_completed"],
    "is_active": true,
    "created_at": "2026-06-20T10:00:00.000Z",
    "recent_deliveries": [
      {
        "delivery_id": "dlv_abc",
        "event": "extraction.job_completed",
        "status": "success",
        "status_code": 200,
        "retry_count": 0,
        "attempted_at": "2026-06-20T10:00:45.000Z"
      }
    ]
  }
}

PATCH /v1/webhooks/:id

Partially update a webhook subscription.

Body Parameters

ParameterTypeRequiredDescription
urlstring❌New callback URL.
eventsstring[]❌Updated event list.
is_activeboolean❌Enable or pause the subscription.
curl -X PATCH https://api.perfectparser.com/v1/webhooks/wh_123 \
  -H "X-API-Key: pp_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Response 200 OK — returns { webhook: { ... } } envelope.

POST /v1/webhooks/:id/test

Sends a synthetic extraction.job_completed payload to your endpoint. The payload includes "test": true so you can distinguish test deliveries.

curl -X POST https://api.perfectparser.com/v1/webhooks/wh_123/test \
  -H "X-API-Key: pp_live_your_secret_key"

Response 200 OK

{
  "test_result": {
    "delivered": true,
    "status_code": 200,
    "response_time_ms": 142,
    "error": null
  }
}

DELETE /v1/webhooks/:id

Soft-deletes a webhook subscription. No further callbacks will be triggered.

Response 204 No Content

Common Error Responses

HTTP StatusError CodeDescription
400INVALID_PAYLOADValidation failed (e.g. non-HTTPS URL in production).
401UNAUTHORIZEDInvalid or missing API key.
404RESOURCE_NOT_FOUNDWebhook not found or belongs to another account.

Previous

Webhooks Overview

Next

Verify Webhooks

On this page