Webhooks API

Manage webhook subscriptions to receive real-time notifications when events occur.

Create Webhook

POST /webhooks

Request Body

{
  "url": "https://your-app.com/flint-webhooks",
  "eventTypes": [
    "document.uploaded",
    "document.processed",
    "extraction.completed"
  ],
  "secret": "your-webhook-secret",
  "active": true,
  "description": "Main webhook for document processing",
  "fieldFilters": {
    "vendor_name": ["Acme Corp", "Beta Inc"],
    "total_amount_gte": ["1000"]
  }
}

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-app.com/flint-webhooks",
    "eventTypes": [
      "document.uploaded",
      "document.processed",
      "extraction.completed"
    ],
    "secret": "wh_secret_xyz789",
    "active": true,
    "createdAt": "2024-01-15T09:00:00Z"
  }
}

List Webhooks

Retrieve all webhook subscriptions.

GET /webhooks

Query Parameters

Parameter	Type	Description
`active`	boolean	Filter by active status
`eventType`	string	Filter by event type
`limit`	integer	Number of results (max 100)
`offset`	integer	Pagination offset

Response

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "wh_abc123",
        "url": "https://your-app.com/flint-webhooks",
        "eventTypes": ["document.processed", "extraction.completed"],
        "active": true,
        "lastTriggered": "2024-01-15T14:30:00Z",
        "successRate": 0.98,
        "createdAt": "2024-01-15T09:00:00Z",
        "updatedAt": "2024-01-15T09:00:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 3
    }
  }
}

Get Webhook

Retrieve a specific webhook subscription.

GET /webhooks/{id}

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-app.com/flint-webhooks",
    "eventTypes": ["document.processed", "extraction.completed"],
    "active": true,
    "description": "Main webhook for document processing",
    "fieldFilters": {
      "vendor_name": ["Acme Corp", "Beta Inc"],
      "total_amount_gte": ["1000"]
    },
    "statistics": {
      "totalDeliveries": 1250,
      "successfulDeliveries": 1225,
      "failedDeliveries": 25,
      "successRate": 0.98,
      "averageResponseTime": "145ms"
    },
    "lastTriggered": "2024-01-15T14:30:00Z",
    "createdAt": "2024-01-15T09:00:00Z",
    "updatedAt": "2024-01-15T09:00:00Z"
  }
}

Update Webhook

Update an existing webhook subscription.

PUT /webhooks/{id}

Request Body

{
  "eventTypes": [
    "document.processed",
    "extraction.completed",
    "template.matched"
  ],
  "active": true,
  "fieldFilters": {
    "total_amount_gte": ["500"]
  }
}

Response

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "eventTypes": [
      "document.processed",
      "extraction.completed",
      "template.matched"
    ],
    "active": true,
    "updatedAt": "2024-01-15T16:45:00Z"
  }
}

Delete Webhook

Delete a webhook subscription.

DELETE /webhooks/{id}

Response

{
  "success": true,
  "message": "Webhook deleted successfully"
}

Test Webhook

Send a test event to your webhook endpoint.

POST /webhooks/{id}/test

Request Body

{
  "eventType": "test.event",
  "payload": {
    "message": "This is a test webhook",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Response

{
  "success": true,
  "data": {
    "deliveryId": "del_test123",
    "status": "delivered",
    "responseCode": 200,
    "responseTime": "125ms",
    "responseHeaders": {
      "content-type": "application/json"
    },
    "responseBody": "OK"
  }
}

Verify Signature

Verify a webhook signature for security.

POST /webhooks/verify-signature

Request Body

{
  "payload": "{\"type\":\"document.processed\",\"data\":{...}}",
  "signature": "sha256=abc123...",
  "secret": "your-webhook-secret"
}

Response

{
  "success": true,
  "data": {
    "valid": true,
    "algorithm": "sha256"
  }
}

Dispatch Event

Manually trigger a webhook event (testing purposes).

POST /webhook.dispatchEvent

Request Body

{
  "type": "test.event",
  "data": {
    "message": "Manual test event",
    "documentId": "doc_abc123"
  },
  "webhookIds": ["wh_abc123", "wh_def456"]
}

Response

{
  "success": true,
  "data": {
    "eventId": "evt_xyz789",
    "dispatched": 2,
    "deliveries": [
      {
        "webhookId": "wh_abc123",
        "status": "queued",
        "deliveryId": "del_123"
      }
    ]
  }
}

Webhook Delivery Logs

Get delivery logs for a webhook.

GET /webhooks/{id}/deliveries

Query Parameters

Parameter	Type	Description
`status`	string	Filter by delivery status
`eventType`	string	Filter by event type
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`limit`	integer	Number of results (max 100)

Response

{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": "del_abc123",
        "eventType": "document.processed",
        "status": "delivered",
        "attempts": 1,
        "responseCode": 200,
        "responseTime": "145ms",
        "createdAt": "2024-01-15T14:30:00Z",
        "deliveredAt": "2024-01-15T14:30:01Z"
      },
      {
        "id": "del_def456",
        "eventType": "extraction.completed",
        "status": "failed",
        "attempts": 3,
        "lastError": "Connection timeout",
        "createdAt": "2024-01-15T13:15:00Z",
        "nextRetryAt": "2024-01-15T13:20:00Z"
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 125
    }
  }
}

Retry Failed Delivery

Retry a failed webhook delivery.

POST /webhooks/deliveries/{deliveryId}/retry

Response

{
  "success": true,
  "data": {
    "deliveryId": "del_def456",
    "status": "queued",
    "scheduledAt": "2024-01-15T15:00:00Z",
    "attempt": 4
  }
}

Event Types

Document Events

document.uploaded - Document uploaded to system
document.processed - OCR/processing completed
document.failed - Processing failed

Extraction Events

extraction.completed - Data extraction finished
extraction.review_required - Manual review needed

Template Events

template.matched - Document matched to template
template.not_matched - No template match found

Webhook Payload Format

All webhook events follow this structure:

{
  "id": "evt_abc123",
  "type": "document.processed",
  "timestamp": "2024-01-15T10:32:15Z",
  "data": {
    "documentId": "doc_abc123",
    "status": "completed",
    "processingTime": "2.3 seconds",
    "confidence": 0.95
  },
  "organization": {
    "id": 123,
    "name": "Acme Corp"
  }
}

Signature Verification

Webhook payloads are signed with HMAC-SHA256:

signature = hmac_sha256(payload, webhook_secret)
header = "sha256=" + hex(signature)

The signature is sent in the Flint-Signature header.

Error Codes

Code	Description
`WEBHOOK_NOT_FOUND`	Webhook ID doesn't exist
`INVALID_URL`	Webhook URL is not valid
`INVALID_EVENT_TYPE`	Unsupported event type
`WEBHOOK_INACTIVE`	Webhook is disabled
`DELIVERY_FAILED`	Webhook delivery failed
`SIGNATURE_INVALID`	Webhook signature verification failed

Webhooks API

On this page