Registering a developer webhook queues a webhook.endpoint_verification event and initially leaves delivery disabled. Your public HTTPS receiver must complete the challenge before the endpoint becomes active.
Verify the request signature using the exact raw body and the signing secret returned at registration. Read the challenge from the verification event and return it in the X-Institution-Challenge response header with a successful 2xx status.
Do not treat any 2xx response without the required challenge as a complete verification implementation. Check the endpoint’s status in Webhooks and use Verify endpoint after correcting the receiver.
Keep the signing secret on the receiving server. If verification fails, inspect safe status and error information without logging credentials or private payloads. Normal event handling should remain separate from the challenge response. Continue using the documented polling route for the underlying resource while webhook delivery is unavailable, so a notification setup issue does not make you assume no results exist.
Was this article helpful?
Tell us whether this answered the question you came with.