Endpoint Validation
Handle the one-time handshake Netchex sends when registering your webhook endpoint
When your webhook URL is registered, Netchex immediately sends a one-time validation request to verify the endpoint is reachable and under your control. No live events are delivered until this handshake completes successfully.
Authenticating Incoming Requests
Every request Netchex sends to your endpoint — including the validation request — includes your shared secret as a token query parameter.
For example, if your endpoint is https://your-app.example.com/webhooks/netchex and your secret is my-secret-token, your registered URL will be:
https://your-app.example.com/webhooks/netchex?token=my-secret-tokenReject any request that does not include the correct token. Return 401 for invalid tokens.
Validation Request
Your endpoint receives a POST with an array containing a single object of type Microsoft.EventGrid.SubscriptionValidationEvent:
[
{
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"topic": "",
"subject": "",
"data": {
"validationCode": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"validationUrl": "https://validation-url.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
"eventTime": "",
"metadataVersion": "1",
"dataVersion": "1"
}
]Required Response
Respond with HTTP 200 and a JSON body echoing the validationCode from data:
{
"validationResponse": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}If your endpoint does not respond correctly within the allotted time, registration fails and no events will be delivered. You'll need to contact your Netchex representative to re-trigger validation.
Example Handler
app.post('/webhooks/netchex', express.json(), (req, res) => {
// Verify shared secret
if (req.query.token !== process.env.NETCHEX_WEBHOOK_SECRET) {
return res.status(401).send('Unauthorized');
}
const events = req.body;
const first = events[0];
// Handle EventGrid subscription validation
if (first?.eventType === 'Microsoft.EventGrid.SubscriptionValidationEvent') {
return res.json({ validationResponse: first.data.validationCode });
}
// Handle live events
res.status(200).send('OK');
// process events asynchronously...
});from flask import Flask, request, jsonify
import os
app = Flask(__name__)
@app.route('/webhooks/netchex', methods=['POST'])
def webhook():
if request.args.get('token') != os.environ['NETCHEX_WEBHOOK_SECRET']:
return '', 401
events = request.json
if events[0].get('eventType') == 'Microsoft.EventGrid.SubscriptionValidationEvent':
return jsonify({'validationResponse': events[0]['data']['validationCode']})
# process events asynchronously...
return '', 200