SendGrid Event Webhook TypeScript Types
TypeScript interfaces for the SendGrid Event Webhook delivery event. Use these types to process email delivery, open, and click events in your application.
SendGrid Event Webhook — Sample JSON
{
"email": "example@example.com",
"timestamp": 1711928400,
"event": "delivered",
"sg_event_id": "sendgrid_internal_event_id_abc123",
"sg_message_id": "14c5d75ce93.dfd.64b469",
"response": "250 OK",
"ip": "167.89.11.234",
"tls": 1,
"cert_err": 0,
"smtp_id": "<14c5d75ce93.dfd.64b469@ismtpd-555>",
"useragent": "Mozilla/4.0 (compatible; MSIE 6.0)",
"category": [
"transactional",
"welcome"
],
"marketing_campaign_id": "sendgrid_campaign_123",
"asm_group_id": 4
}Generated TypeScript
export interface SendGridDeliveryEvent {
email: string;
timestamp: number;
event: string;
sg_event_id: string;
sg_message_id: string;
response: string;
ip: string;
tls: number;
cert_err: number;
smtp_id: string;
useragent: string;
category: string[];
marketing_campaign_id: string;
asm_group_id: number;
}How to use
Copy the TypeScript above into a types.ts file in your project. Import the root interface and use it to type your API responses: const data: SendGridDeliveryEvent = await res.json()
Working with a different JSON payload? Paste any JSON and generate TypeScript interfaces instantly.
Convert your own JSON →FAQ
SendGrid sends an array of events — why does this show a single object?
SendGrid batches events and sends them as a JSON array in the request body. Each element is one event. When building your handler, parse the array and process each event individually: const events: SendGridDeliveryEvent[] = await req.json(). This sample shows the shape of one element.
What is the difference between 'delivered' and 'processed' events in SendGrid?
'processed' fires when SendGrid accepts the email for sending (before it reaches the recipient's server). 'delivered' fires when the recipient's mail server accepts the message. A 'processed' event without a subsequent 'delivered' usually means a bounce or deferral.
How do I distinguish transactional from marketing emails in the webhook?
Use the category array you set when sending the email, or use the asm_group_id (unsubscribe group ID — only present on marketing emails). For transactional emails, asm_group_id is absent. You can also add a custom field like { type: 'transactional' } to the email's custom_args.