VendorHearth Pro uses a Square webhook to receive payment updates from Square.
The webhook works in the background and helps VendorHearth recognize changes to payments after they have been created.
What Is a Webhook? #
A webhook is a way for Square to send information back to your VendorHearth website automatically.
Instead of VendorHearth constantly asking Square whether a payment has changed, Square can send an update when a relevant payment event occurs.
In simple terms:
Vendor makes payment → Square processes payment → Square sends an update → VendorHearth receives the update
Why VendorHearth Needs the Webhook #
A payment does not always remain in the same status throughout its entire lifecycle.
VendorHearth needs to know when relevant payment information changes so its records can stay synchronized with the payment activity reported by Square.
The webhook provides that communication path.
The VendorHearth Webhook URL #
VendorHearth generates the webhook URL required for the Square integration.
You can find this URL in your VendorHearth Square payment settings.
Copy the URL exactly as displayed and use it when creating the webhook subscription in the Square Developer Console.
Do not replace it with your website homepage or another WordPress URL.
The payment.updated Event #
The VendorHearth Square webhook should be subscribed to:
payment.updated
Square sends this event when an existing payment is updated.
VendorHearth can then process the notification and update the corresponding payment information as appropriate.
Webhook Signature Key #
Square provides a Signature Key for the webhook subscription.
This key is entered into the VendorHearth Square settings.
VendorHearth uses it to verify webhook notifications.
This helps ensure that incoming payment notifications actually originated from Square rather than an unrelated source attempting to contact the webhook endpoint.
Keep the Signature Key Private #
Treat the Webhook Signature Key as sensitive information.
Do not:
- Publish it on your website
- Include it in public documentation
- Share it in screenshots
- Post it in public support discussions
Only authorized administrators should have access to your payment configuration.
Sandbox and Production Webhooks #
Square maintains separate Sandbox and Production environments.
Make sure the webhook configuration corresponds to the environment currently being used by VendorHearth.
If you test VendorHearth in Sandbox and later move to Production, review the Production webhook configuration as part of that transition.
Do not assume that completing the Sandbox setup automatically completes the Production setup.
If You Recreate the Webhook #
If you delete and recreate your Square webhook subscription, review the Signature Key.
A newly created subscription may require you to update the key stored in VendorHearth.
If VendorHearth has the wrong Signature Key, it may reject incoming notifications because they cannot be successfully verified.
If Payments Are Not Updating #
If a Square payment is successful but VendorHearth is not reflecting the expected payment update, check:
- The webhook subscription exists.
- The correct VendorHearth Webhook URL is being used.
payment.updatedis selected.- The correct environment is being used.
- The Signature Key in VendorHearth matches the Square webhook subscription.
- The VendorHearth website is publicly accessible.
- HTTPS is functioning correctly.
Also verify that your other Square credentials are correct.
Do Not Disable the Webhook After Setup #
The webhook is part of the ongoing Square integration.
It is not something that is only needed during initial setup.
Keep the VendorHearth webhook subscription active while you are using Square payments with VendorHearth.
The Webhook Does Not Store Your Square Credentials Publicly #
The webhook URL is an endpoint that receives notifications.
It is not your Square Access Token.
Security is provided in part through verification using the Signature Key.
Your Square Access Token and Webhook Signature Key should still remain private.
When Should You Check the Webhook? #
You generally only need to revisit the webhook configuration when:
- Initially setting up Square
- Moving from Sandbox to Production
- Troubleshooting payment updates
- Recreating the Square webhook
- Changing the website or integration configuration
- Updating credentials related to the integration
Once configured correctly, the webhook is designed to operate in the background.
Next Step #
Continue to Testing Your Square Connection to verify that VendorHearth and Square are communicating correctly before relying on the integration for vendor payments.
