NUDG3 Webhooks API
The Webhooks API from NUDG3 — 6 operation(s) for webhooks.
The Webhooks API from NUDG3 — 6 operation(s) for webhooks.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nudg3-ai:nudg3-ai-webhooks-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Nudg3 Webhooks API
description: '# Nudg3 Brand Intelligence API
The Nudg3 API provides programmatic access to brand visibility analytics across AI providers.
## Public API v1
The Public API (`/api/v1/`) is designed for third-party integrations and provides:
### Analytics Endpoints (Tier 1 - Basic)
- Brand visibility scores and trends
- Sentiment analysis across AI responses
- Source citation tracking
- Prompt performance metrics
- Google AI Overview (AIO) coverage
### Export Endpoints (Tier 2 - Premium)
- Full response data exports (CSV/TSV)
- Source citations bulk download
- Dashboard time-series data
- Prompt-mention pair exports
## Authentication
### API Key (Public API v1)
```bash
curl -H "Authorization: Bearer nudg3_live_ak_xxx..." \
https://api.nudg3.com/api/v1/dashboard
```
### JWT (Dashboard API)
```bash
curl -H "Authorization: Bearer eyJ..." \
https://api.nudg3.com/analytics/dashboard
```
## Rate Limits
| Tier | Per Minute | Per Hour | Monthly Quota |
|------|------------|----------|---------------|
| Basic | 60 | 600 | 5,000 |
| Premium | 300 | 3,000 | 50,000 |
## Response Format
All responses follow a standard envelope:
```json
{
"success": true,
"data": { ... },
"message": "Success"
}
```
## Support
- Documentation: https://docs.nudg3.com
- API Status: https://status.nudg3.com
- Support: support@nudg3.com'
version: 1.1.0
termsOfService: https://nudg3.com/terms
contact:
name: Nudg3 API Support
url: https://nudg3.com/support
email: support@nudg3.com
license:
name: Proprietary
url: https://nudg3.com/license
servers:
- url: https://api.nudg3.com
description: Production API
- url: https://api-staging.nudg3.com
description: Staging API (for testing)
- url: http://localhost:8000
description: Local Development
tags:
- name: Webhooks
paths:
/webhooks/payfast:
post:
tags:
- Webhooks
summary: Payfast Webhook
description: 'Handle PayFast ITN (Instant Transaction Notification).
SECURITY CRITICAL: This endpoint processes payments and activates subscriptions.
PayFast sends webhooks for:
- COMPLETE: Payment successful
- FAILED: Payment failed
- CANCELLED: Payment cancelled by user
Process:
1. Parse webhook data
2. Validate merchant ID
3. Verify signature
4. Validate timestamp (reject old webhooks)
5. Check idempotency (prevent duplicate processing)
6. Validate payment amount
7. Create transaction record
8. Process successful payment (activate subscription via SubscriptionService)
9. Send confirmation email
Error Handling:
- All errors are caught and logged to failed_webhooks table
- Returns 200 OK even on failure to prevent PayFast retries
- Failed webhooks can be manually investigated and retried
Returns:
{"status": "ok"} on success or failure (always 200)
Security Notes:
- Does not require JWT authentication (external webhook)
- IP whitelist prevents requests from non-PayFast servers
- Validates signature to prevent spoofing
- Only stores safe metadata (PCI compliance)'
operationId: payfast_webhook_webhooks_payfast_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/webhooks/postmark/bounce:
post:
tags:
- Webhooks
summary: Handle Postmark bounce webhook
description: Receives bounce notifications from Postmark. Logs bounce events for deliverability monitoring.
operationId: handle_bounce_webhooks_postmark_bounce_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/webhooks/postmark/spam-complaint:
post:
tags:
- Webhooks
summary: Handle Postmark spam complaint webhook
description: Receives spam complaint notifications. These are critical deliverability signals.
operationId: handle_spam_complaint_webhooks_postmark_spam_complaint_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/webhooks/postmark/delivery:
post:
tags:
- Webhooks
summary: Handle Postmark delivery webhook
description: Receives delivery confirmations. Used for delivery rate monitoring.
operationId: handle_delivery_webhooks_postmark_delivery_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/webhooks/stripe:
post:
tags:
- Webhooks
summary: Stripe Webhook
description: 'Handle Stripe webhook events.
SECURITY CRITICAL: This endpoint processes payments and activates subscriptions.
Supported events:
- checkout.session.completed: Initial subscription activation
- invoice.payment_succeeded: Recurring payment success
- invoice.payment_failed: Payment failure
- customer.subscription.deleted: Subscription cancelled externally
Process:
1. Read raw request body (required for signature verification)
2. Verify signature using Stripe SDK
3. Parse event and extract metadata
4. Check idempotency (prevent duplicate processing)
5. Process event (activate subscription, record transaction)
6. Send confirmation email (if applicable)
Error Handling:
- All errors are caught and logged to failed_webhooks table
- Returns 200 OK even on failure to prevent Stripe retries
- Failed webhooks can be manually investigated and retried
Returns:
{"status": "ok"} on success or failure (always 200)
Security Notes:
- Does not require JWT authentication (external webhook)
- Validates signature to prevent spoofing
- Uses raw body for signature verification
- Only stores safe metadata (PCI compliance)'
operationId: stripe_webhook_webhooks_stripe_post
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/system/v3-webhook:
post:
tags:
- Webhooks
summary: Cloro Webhook
description: 'Receive Cloro async task completion webhook.
Flow:
1. Look up CloroTask by cloro_task_id
2. Map Cloro response to ProviderResponse fields
3. Create ProviderResponse record
4. Persist Source + Citation records via persist_sources_inline()
5. Update CloroTask status + provider_response_id
6. Update CollectionRun tracking (response_ids)
Returns 200 on success, 404 if task not found.'
operationId: cloro_webhook_system_v3_webhook_post
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Cloro Webhook System V3 Webhook Post
components:
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: '
API Key authentication for Public API v1 endpoints.
**Format:** `nudg3_live_ak_xxx...` or `nudg3_test_ak_xxx...`
**Usage:**
```
Authorization: Bearer nudg3_live_ak_your_key_here
```
Or use the header:
```
X-API-Key: nudg3_live_ak_your_key_here
```
**Obtain API Keys:**
Generate API keys from your Nudg3 dashboard under Settings > API Keys.
**Tiers:**
- **Basic:** `read:analytics` scope - Analytics endpoints only
- **Premium:** `read:analytics` + `export:data` scopes - Analytics + Exports
'
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: '
JWT authentication for internal dashboard endpoints.
Obtain tokens via `/auth/login` endpoint.
'
externalDocs:
description: Nudg3 API Documentation
url: https://docs.nudg3.com/api