Webhooks API

Create, manage, and test webhooks programmatically via the REST API. Requires an API key with the webhooks scope.

Pro plan — The Webhooks API requires a Pro plan to create and manage webhooks. Upgrade from Billing & Plans.

Base URL

https://projectfeed.app/api/v1/webhooks

Endpoints

GET/api/v1/webhooks

List all webhooks for the authenticated workspace.

POST/api/v1/webhooks

Create a new webhook. Returns the webhook object including the signing secret (shown only once).

GET/api/v1/webhooks/:id

Retrieve a specific webhook by ID.

PATCH/api/v1/webhooks/:id

Update a webhook's name, URL, events, or enabled status.

DELETE/api/v1/webhooks/:id

Delete a webhook. All pending deliveries are cancelled.

POST/api/v1/webhooks/:id/test

Send a test event to the webhook endpoint. Returns the delivery result.

POST/api/v1/webhooks/:id/regenerate-secret

Regenerate the signing secret. The old secret is immediately invalidated.

GET/api/v1/webhooks/:id/deliveries

List recent deliveries for a webhook, including status codes and response times.

POST/api/v1/webhooks/:id/deliveries/:deliveryId/retry

Retry a failed delivery. The payload is resent as-is.

Webhook Object

{
  "id": "wh_abc123",
  "name": "My Webhook",
  "url": "https://your-server.com/webhook",
  "events": ["post.created", "post.updated"],
  "enabled": true,
  "failureCount": 0,
  "secret": "whsec_...",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

idUnique webhook identifier. Prefixed with wh_.

nameHuman-readable name for the webhook. Max 100 characters.

urlHTTPS endpoint that receives webhook deliveries.

eventsArray of event types this webhook is subscribed to.

enabledWhether the webhook is active. Disabled after 10 consecutive failures.

failureCountNumber of consecutive failed deliveries. Resets to 0 on success.

secretSigning secret for HMAC-SHA256 verification. Only returned on creation and secret regeneration.

Delivery Object

{
  "id": "del_xyz789",
  "eventType": "post.created",
  "success": true,
  "responseStatus": 200,
  "duration": 142,
  "error": null,
  "createdAt": "2025-01-15T10:31:00Z"
}

Authentication

All webhook API endpoints require an API key with the webhooks scope. Pass the key in the Authorization header.

Webhook access also follows the key owner's current workspace role and webhook ownership. Members can only create and manage webhooks they created themselves, while workspace admins and owners can manage all workspace webhooks. Viewers cannot use webhook endpoints.

Requests that authenticate but fail those ownership or role checks return 403.

Authorization: Bearer pf_live_your_api_key

Service-to-service routes

The Convex deployment also exposes internal routes that only Project Feed infrastructure calls. These are documented here for operator visibility — they are not part of the customer API and cannot be called with an API key.

POST/api/webhooks/email-reply

Called by the email-receiver Cloudflare Worker when a user replies to a notification email. The Worker parses the inbound MIME, verifies the signed local-part token, and requires a Cloudflare-authored ARC result set to show an aligned DKIM pass or ARC-passed DMARC pass before POSTing the normalized payload here. Convex requires the Worker's authenticated-message flag, re-verifies the token, checks the From address matches the user's stored email, re-checks organization membership, applies a per-user rate limit, dedupes by Message-ID, and inserts the reply as a threaded comment.

Signed with HMAC-SHA256 over ${timestamp}.${body} using EMAIL_RECEIVER_SECRET; the signature is sent in X-Email-Receiver-Signature, the timestamp in X-Timestamp. Requests older than 5 minutes are rejected.

Learn about webhook concepts

See the webhooks guide for event types, security, and reliability details.

Webhooks Guide