Webhook Configuration
A webhook endpoint consists of a URL, the list of events to send to that URL and a secret used to sign the requests. You can manage endpoints in the dashboard under Settings β Webhooks or through the API. A team can define up to 10 endpoints; that way you can, for example, route billing events to your accounting service and Detector events to your monitoring service separately.
Prepare the HTTPS Endpoint
Open a publicly reachable HTTPS address on your server that accepts POST requests. Plain http:// addresses, self-signed certificates and private IP ranges (10.0.0.0/8, 192.168.0.0/16, localhost) are rejected. TLS 1.2 or higher is required. The endpoint must return 2xx within 10 seconds of receiving the request; push long-running work onto a queue and answer straight away.
Create the Endpoint and Choose Events
Click "Add endpoint" in the dashboard or use the API. List only the events you need in the events field; * selects every event but creates needless traffic. The event list can be updated at any time and the change takes effect immediately.
Store the Secret
The secret starting with whsec_ is shown only once, in the creation response. Store it in an environment variable such as INCAPON_WEBHOOK_SECRET or in your secrets manager. When you rotate the secret, the old one stays valid for another 24 hours; both signatures are sent during that window, so you can switch over without downtime. For the verification code see Webhook Signature Verification.
Send a Test Event
Before going live, send a sample event with the "Send test" button in the dashboard or the test-dispatch endpoint. Test events are signed exactly like real ones, carry "test": true in the payload and spend no credits. The delivery result, response code and duration appear in the delivery log.
Configuring via the API
# Create an endpoint
curl -X POST https://api.incapon.com/v2.4/webhooks/endpoints \
-H "Authorization: Bearer $INCAPON_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/incapon",
"events": ["signature.compared", "document.processed", "credits.low"],
"description": "Production server"
}'
# Send a test event
curl -X POST https://api.incapon.com/v2.4/webhooks/test-dispatch \
-H "Authorization: Bearer $INCAPON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"endpoint_id": "whe_3fK8s2", "event_type": "signature.compared"}'import os
import incapon
client = incapon.Client(api_key=os.environ["INCAPON_API_KEY"])
endpoint = client.webhooks.endpoints.create(
url="https://example.com/webhooks/incapon",
events=["signature.compared", "document.processed", "credits.low"],
description="Production server",
)
# The secret is returned only in this response, store it right away
print(endpoint.secret) # whsec_...
client.webhooks.test_dispatch(endpoint_id=endpoint.id, event_type="signature.compared")localhost addresses are not accepted. During development, expose your local server through an HTTPS tunnel and define a separate endpoint with a test key (inc_test_...).