Small and medium business | Business Central, N...

webhook registration issue

(3) Share

Report

Posted on by KC-23040030-0

I am trying to register a webhook so I can sync our internal database with any customer or dimension changes. I have the api up and running but I get "Service has not provided a valid validation token" error when I post to the subscription url: https://api.businesscentral.dynamics.com/v2.0/{tenantId}/Production/api/v2.0/subscriptions

I get token properly in return when I test the get method directly (something like https://a1b2c3d4.ngrok-free.app/api/webhook/customer?validationToken=test123 with ngrok) but it doesn't look like BC is hitting the get method with correct validation token with post method. Is there anything that I need to set up in BC? I would really appreciate if someone can shed some light on this.

Thank you.

Categories:

Dynamics 365 Business Central

I have the same question (0)

All responses (2)

Answers (0)

Suggested answer

Holly Huffman 6,530 Super User 2025 Season 2 on at

Like (0)

Report
Good morning, afternoon, or evening depending on your location!

The error "Service has not provided a valid validation token" typically occurs during the webhook registration process in Dynamics 365 Business Central when the validation handshake fails. Here’s how you can troubleshoot and resolve this issue -

Steps to Resolve Webhook Registration Issue

Ensure Proper Handshake Response:

When Business Central sends a request to your notificationUrl with the validationToken parameter, your service must respond with:

HTTP Status Code 200.

The validationToken value returned as raw text in the response body.

Example code snippet for handling the handshake:
app.get('/api/webhook/customer', (req, res) => {
    const validationToken = req.query.validationToken;
    if (validationToken) {
        res.status(200).send(validationToken);
    } else {
        res.status(400).send('Validation token missing');
    }
});

Verify Notification URL Accessibility:

Ensure the notificationUrl is publicly accessible and reachable by Business Central.

If you’re using ngrok, confirm that the URL is active and correctly configured.

Check API Subscription Request Format:

The POST request to register the webhook must include the correct JSON structure:
{
    "notificationUrl": "https://a1b2c3d4.ngrok-free.app/api/webhook/customer",
    "resource": "/api/v2.0/companies({companyId})/customers",
    "clientState": "optionalValueOf2048"
}

Ensure the resource matches the entity you want to subscribe to (e.g., /customers or /dimensions).

Validate Webhook Configuration in Business Central:

Confirm that the API permissions are correctly set up in Business Central.

Ensure your user has the necessary roles (e.g., System Administrator or Environment Maker) to register webhooks.

Check for Known Issues:

Business Central may have specific requirements for webhook registration. Review the Microsoft Learn documentation for detailed guidelines.

Test with a Simpler Endpoint:

If the issue persists, test the webhook registration with a simpler endpoint (e.g., a basic HTTP server) to isolate the problem.

Additional Resources

You can find more details on webhook registration and troubleshooting here.

Hope this helps some!

Was this reply helpful? Yes No
Suggested answer

Khushbu Rajvi. 20,439 Super User 2025 Season 2 on at

Like (1)

Report

Please check this: https://demiliani.com/2019/12/10/webhooks-with-dynamics-365-business-central/

https://www.kauffmann.nl/2020/11/28/how-to-test-business-central-webhooks/

https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/dynamics-subscriptions

https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v1.0/dynamics_subscriptions

https://community.dynamics.com/blogs/post/?postid=b2bced4d-002a-42fd-82f8-dc95a6715518

Was this reply helpful? Yes No

Join the conversation

Community site session details

webhook registration issue

Helpful resources

Quick Links

Responsible AI policies

Neeraj Kumar – Community Spotlight

Congratulations to the November Top 10 Community Leaders!

Leaderboard > Small and medium business | Business Central, NAV, RMS

Featured topics

Product updates

Community site session details

webhook registration issue

Helpful resources

Quick Links

Responsible AI policies

Neeraj Kumar – Community Spotlight

Congratulations to the November Top 10 Community Leaders!

Subscribe to this forum!

Select categories

Leaderboard > Small and medium business | Business Central, NAV, RMS

Featured topics

Product updates