New to VisionScaper?
Start here
Help Center › Get your API keys › SendGrid Event Webhook and secret
SendGrid Event Webhook and secret
Add VisionScaper's address as a SendGrid Event Webhook, with a note about SendGrid's own signing method.
An Event Webhook lets SendGrid report delivery, bounces, spam reports and unsubscribes to your site.
Warning: Read “Known gap”. VisionScaper’s signature test may not match SendGrid’s.
Before you start
- SendGrid is set up (see “Get your SendGrid API key”).
Steps
- In the SendGrid console go to Settings > Mail Settings.
- Under Webhook Settings, click Event Webhooks, then Create new webhook.
- Switch Enabled on. Add a Friendly Name if you like.
- In Post URL, enter your site’s address ending
/wp-json/dreamscaper/v1/msg/webhook/sendgrid. (The plugin registers this path. The screen does not print it for SendGrid. Not verified on screen.) - In Actions to be posted, tick: delivered, bounce, dropped, spam report, unsubscribe, group unsubscribe. These are the event names the code uses.
- Look at Security features: Signature Verification and OAuth Verification. See the gap below.
- Click Test Your Integration to send a sample, then Save.
- Put your chosen secret into SendGrid webhook secret in Settings → VisionScaper Messaging and save.
What VisionScaper does
| SendGrid event | Result |
|---|---|
| delivered | Marked delivered |
| bounce | Bounced; contact flagged |
| dropped | Failed |
| spamreport | Opt-out recorded |
| unsubscribe, group_unsubscribe | Opt-out recorded |
Known gap: the signature check
- VisionScaper expects a header
X-Sendgrid-Signatureholding the hex HMAC-SHA256 of the body using the SendGrid webhook secret. - SendGrid’s page says it offers Signature Verification and OAuth Verification, but it does not name the headers here. Its signature feature is not described as a shared HMAC secret on that page, and I did not open the security-features page.
- So whether SendGrid can call VisionScaper successfully is unverified. Expect “Bad signature” (403) if not.
- Sending is unaffected.
Tips
- If your server does not answer with a 2xx status, SendGrid retries for up to 24 hours.
- Use a tunnel for local testing; localhost is not reachable.
If something goes wrong
- 403 in SendGrid’s log. See the gap.
- No events. The webhook is disabled or the wrong actions are ticked.
Sources
- Twilio SendGrid, Event Webhook setup: https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook (read 2026-10-15)
- Plugin: includes/messaging-providers.php.