Documentation Index Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
This guide covers how to create, test, and update a webhook, attach it to a job
or monitor, and troubleshoot delivery issues.
Before you begin
You have a CatchAll API key.
You have a publicly accessible HTTPS endpoint ready to receive POST requests,
or use webhook.site for testing.
Create webhook A webhook is created independently of any job or monitor. Once created, you
attach it to one or more resources.
curl -X POST "https://catchall.newscatcherapi.com/catchAll/webhooks" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Layoffs Alert", "url": "https://your-endpoint.com/catchall", "type": "generic", "delivery_mode": "full" }'
Response:
{ "success" : true , "message" : "Webhook created successfully." , "webhook" : { "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "name" : "Layoffs Alert" , "url" : "https://your-endpoint.com/catchall" , "type" : "generic" , "delivery_mode" : "full" , "method" : "POST" , "is_active" : true } }
Save the webhook.id — you use it to attach the webhook to resources.
For supported values of type, delivery_mode, and auth, see
Create webhook API reference .
Test before attaching Before attaching a webhook to a live resource, verify that your endpoint is
reachable and auth is configured correctly:
curl -X POST "https://catchall.newscatcherapi.com/catchAll/webhooks/{webhook_id}/test" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'
Response:
{ "success" : true , "message" : "Test delivery succeeded." , "http_status_code" : 200 , "response_body" : "ok" }
If success is false, check http_status_code and response_body to
diagnose the issue before proceeding.
Attach webhook to job or monitor You can attach a webhook to a job or monitor at creation time, or assign it to
an existing resource afterward.
At creation time Pass webhook_ids when submitting a job or creating a monitor:
cURL — job
cURL — monitor
Python
TypeScript
Java
curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Tech layoffs in the US", "webhook_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"] }'
After creation Assign a webhook to an existing resource using the assignment endpoint:
curl -X POST "https://catchall.newscatcherapi.com/catchAll/webhooks/{webhook_id}/resources" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "resource_type": "monitor", "resource_id": "3fec5b07-8786-46d7-9486-d43ff67eccd4" }'
Each resource supports up to 5 webhooks. Each webhook can be assigned to
multiple resources.
Update webhook Update any field on an existing webhook. Only supplied fields are changed:
curl -X PATCH "https://catchall.newscatcherapi.com/catchAll/webhooks/{webhook_id}" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://new-endpoint.com/catchall", "auth": { "type": "bearer", "token": "NEW_TOKEN" } }'
To pause deliveries without deleting the webhook, set is_active to false.
Handle deliveries Your endpoint must meet the following requirements and handle incoming requests
reliably.
Endpoint requirements Your endpoint must:
Return a 2xx status code within 5 seconds.Be publicly accessible — localhost and private network addresses are not supported.Use HTTPS — HTTP endpoints are not accepted.Accept POST requests with a JSON body.
Return 200 before processing to avoid timeouts. Process the payload
asynchronously:
from flask import Flask, request, jsonify app = Flask( __name__ ) @app.route ( "/catchall/webhook" , methods = [ "POST" ]) def handle_webhook (): payload = request.json # Return 200 immediately, then process process_async(payload) return jsonify({ "status" : "received" }), 200 def process_async ( payload ): # Your processing logic here pass
import express from "express" ; const app = express (); app . use ( express . json ()); app . post ( "/catchall/webhook" , ( req , res ) => { const payload = req . body ; // Return 200 immediately, then process res . status ( 200 ). json ({ status: "received" }); processAsync ( payload ); }); async function processAsync ( payload : any ) { // Your processing logic here }
@ RestController public class WebhookController { @ PostMapping ( "/catchall/webhook" ) public ResponseEntity < Map < String , String >> handleWebhook ( @ RequestBody Map < String , Object > payload ) { // Return 200 immediately, then process CompletableFuture . runAsync (() -> processAsync (payload)); return ResponseEntity . ok ( Map . of ( "status" , "received" )); } private void processAsync ( Map < String , Object > payload ) { // Your processing logic here } }
Debug deliveries Use the delivery history endpoint to inspect past dispatch outcomes:
curl "https://catchall.newscatcherapi.com/catchAll/webhook-history?resource_type=monitor&resource_id={monitor_id}" \ -H "x-api-key: YOUR_API_KEY"
Each record shows the HTTP status code returned by your endpoint, the delivery
outcome (SUCCESS or FAILED), and any error or warning messages.
See also 
