SendGrid Event Webhook

asyncapi: 2.6.0
info:
  title: SendGrid Event Webhook
  description: >-
    The SendGrid Event Webhook delivers near real-time event data about
    your email activity via HTTP POST requests. SendGrid batches events
    into arrays and sends them to your configured webhook URL. Events
    cover the full email lifecycle including delivery, engagement, and
    suppression actions. You can use this data to monitor deliverability,
    track recipient engagement, and maintain suppression lists.
  version: '3.0.0'
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
  termsOfService: https://www.twilio.com/legal/tos
  externalDocs:
    description: Event Webhook Reference
    url: https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/event
servers:
  customerEndpoint:
    url: '{webhookUrl}'
    protocol: https
    description: >-
      The customer-configured HTTPS endpoint that receives webhook POST
      requests from SendGrid. You configure this URL in the SendGrid
      Event Webhook settings.
    variables:
      webhookUrl:
        description: Your webhook receiver URL
    security:
      - signedWebhook: []
      - oAuth2: []
channels:
  /webhook/event:
    description: >-
      SendGrid posts batched email event data to your configured webhook
      URL. Each POST request contains a JSON array of up to 1000 or more
      event objects. Events include delivery events (processed, dropped,
      delivered, deferred, bounce) and engagement events (open, click,
      spam report, unsubscribe, group unsubscribe, group resubscribe).
    publish:
      operationId: receiveEmailEvents
      summary: Receive batched email event notifications
      description: >-
        SendGrid sends HTTP POST requests containing a JSON array of
        event objects to your webhook URL. Each event object includes
        common fields such as the recipient email, timestamp, event
        type, and SendGrid message identifiers. Event-specific fields
        provide additional context such as bounce reasons, clicked URLs,
        or user agent strings.
      message:
        oneOf:
          - $ref: '#/components/messages/ProcessedEvent'
          - $ref: '#/components/messages/DroppedEvent'
          - $ref: '#/components/messages/DeliveredEvent'
          - $ref: '#/components/messages/DeferredEvent'
          - $ref: '#/components/messages/BounceEvent'
          - $ref: '#/components/messages/OpenEvent'
          - $ref: '#/components/messages/ClickEvent'
          - $ref: '#/components/messages/SpamReportEvent'
          - $ref: '#/components/messages/UnsubscribeEvent'
          - $ref: '#/components/messages/GroupUnsubscribeEvent'
          - $ref: '#/components/messages/GroupResubscribeEvent'
components:
  securitySchemes:
    signedWebhook:
      type: httpApiKey
      name: X-Twilio-Email-Event-Webhook-Signature
      in: header
      description: >-
        ECDSA signature for verifying the authenticity of webhook
        requests. Enable Signed Event Webhook in your SendGrid
        settings to use this verification method.
    oAuth2:
      type: oauth2
      description: >-
        OAuth 2.0 client credentials flow for authenticating webhook
        requests. Configure OAuth client ID, client secret, and token
        URL in your Event Webhook settings.
      flows:
        clientCredentials:
          tokenUrl: '{oauthTokenUrl}'
          scopes: {}
  messages:
    ProcessedEvent:
      name: Processed
      title: Processed Event
      summary: >-
        SendGrid accepted the message and will attempt delivery.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ProcessedEvent'
    DroppedEvent:
      name: Dropped
      title: Dropped Event
      summary: >-
        SendGrid dropped the message due to invalid headers, spam
        content, unsubscribed recipient, bounced address, or quota
        limits.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DroppedEvent'
    DeliveredEvent:
      name: Delivered
      title: Delivered Event
      summary: >-
        SendGrid successfully delivered the message to the receiving
        mail server.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DeliveredEvent'
    DeferredEvent:
      name: Deferred
      title: Deferred Event
      summary: >-
        The receiving server temporarily rejected the message and
        SendGrid will retry delivery.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/DeferredEvent'
    BounceEvent:
      name: Bounce
      title: Bounce Event
      summary: >-
        The receiving server permanently or temporarily rejected the
        message.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/BounceEvent'
    OpenEvent:
      name: Open
      title: Open Event
      summary: >-
        The recipient opened the HTML email message.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/OpenEvent'
    ClickEvent:
      name: Click
      title: Click Event
      summary: >-
        The recipient clicked a link within the email message.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/ClickEvent'
    SpamReportEvent:
      name: SpamReport
      title: Spam Report Event
      summary: >-
        The recipient marked the email as spam.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/SpamReportEvent'
    UnsubscribeEvent:
      name: Unsubscribe
      title: Unsubscribe Event
      summary: >-
        The recipient unsubscribed from all emails.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/UnsubscribeEvent'
    GroupUnsubscribeEvent:
      name: GroupUnsubscribe
      title: Group Unsubscribe Event
      summary: >-
        The recipient unsubscribed from a specific suppression group.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/GroupUnsubscribeEvent'
    GroupResubscribeEvent:
      name: GroupResubscribe
      title: Group Resubscribe Event
      summary: >-
        The recipient resubscribed to a specific suppression group.
      contentType: application/json
      payload:
        $ref: '#/components/schemas/GroupResubscribeEvent'
  schemas:
    BaseEvent:
      type: object
      description: >-
        Common fields present on all SendGrid Event Webhook events.
      required:
        - email
        - event
        - sg_event_id
        - sg_message_id
        - timestamp
      properties:
        email:
          type: string
          format: email
          description: >-
            The email address of the recipient.
        event:
          type: string
          description: >-
            The type of event that occurred.
        sg_event_id:
          type: string
          description: >-
            A unique identifier for this event generated by SendGrid.
        sg_message_id:
          type: string
          description: >-
            A unique identifier for the message associated with this
            event, generated by SendGrid.
        timestamp:
          type: integer
          description: >-
            The Unix timestamp of when the event occurred.
        smtp-id:
          type: string
          description: >-
            A unique identifier attached to the message by the
            originating SMTP server.
        category:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            Categories assigned to the message for tracking purposes.
            May be a single string or an array of strings.
        asm_group_id:
          type: integer
          description: >-
            The ID of the suppression group that the recipient is
            associated with.
        unique_args:
          type: object
          additionalProperties: true
          description: >-
            Custom key-value pairs passed with the message using
            unique_args (SMTP API / v2 Mail Send) or custom_args
            (v3 Mail Send).
        marketing_campaign_id:
          type: integer
          description: >-
            The ID of the Marketing Campaign that generated this event,
            if applicable.
        marketing_campaign_name:
          type: string
          description: >-
            The name of the Marketing Campaign that generated this
            event, if applicable.
    ProcessedEvent:
      description: >-
        Indicates that SendGrid has accepted the message and will
        attempt to deliver it.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: processed
            pool:
              type: object
              description: >-
                Information about the IP pool used for sending.
              properties:
                name:
                  type: string
                  description: >-
                    The name of the IP pool.
                id:
                  type: integer
                  description: >-
                    The ID of the IP pool.
    DroppedEvent:
      description: >-
        Indicates that SendGrid dropped the message and will not
        deliver it. Messages are dropped due to invalid headers,
        spam content, an unsubscribed recipient, a previously bounced
        address, or exceeding sending quotas.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: dropped
            reason:
              type: string
              description: >-
                The reason why the message was dropped.
            status:
              type: string
              description: >-
                The SMTP status code associated with the drop.
    DeliveredEvent:
      description: >-
        Indicates that the receiving mail server accepted the message
        for delivery to the recipient.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: delivered
            response:
              type: string
              description: >-
                The full SMTP response string from the receiving server,
                such as "250 OK".
    DeferredEvent:
      description: >-
        Indicates that the receiving server temporarily rejected the
        message. SendGrid will continue to retry delivery.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: deferred
            attempt:
              type: integer
              minimum: 1
              description: >-
                The number of delivery attempts SendGrid has made for
                this message.
            response:
              type: string
              description: >-
                The full response string from the receiving server
                explaining the deferral.
    BounceEvent:
      description: >-
        Indicates that the receiving server rejected the message. A
        hard bounce means the address is permanently invalid. A blocked
        bounce is a temporary or soft rejection.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: bounce
            bounce_classification:
              type: string
              enum:
                - Invalid Address
                - Technical
                - Content
                - Reputation
                - Frequency/Volume
                - Mailbox Unavailable
                - Unclassified
              description: >-
                The classification of the bounce indicating the
                general category of the rejection reason.
            reason:
              type: string
              description: >-
                The detailed rejection reason provided by the
                receiving server.
            status:
              type: string
              description: >-
                The SMTP status code associated with the bounce.
            type:
              type: string
              enum:
                - bounce
                - blocked
              description: >-
                The type of bounce. A value of "bounce" indicates a
                hard bounce (permanent failure). A value of "blocked"
                indicates a soft bounce (temporary failure).
    OpenEvent:
      description: >-
        Indicates that the recipient opened the HTML email message.
        Open tracking requires a transparent tracking pixel embedded
        in the HTML content.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: open
            sg_machine_open:
              type: boolean
              description: >-
                Indicates whether the open was detected as an
                automated or machine-generated open rather than a
                human interaction.
            useragent:
              type: string
              description: >-
                The user agent string of the client that opened
                the email.
    ClickEvent:
      description: >-
        Indicates that the recipient clicked on a link within the
        email message.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: click
            ip:
              type: string
              description: >-
                The IP address of the recipient who clicked the link.
            url:
              type: string
              format: uri
              description: >-
                The URL that was clicked by the recipient.
            url_offset:
              type: object
              description: >-
                The position and type of the clicked link within
                the message body.
              properties:
                index:
                  type: integer
                  minimum: 0
                  description: >-
                    The zero-based index of the link in the message.
                type:
                  type: string
                  enum:
                    - html
                    - text
                  description: >-
                    Whether the link was in the HTML or plain text
                    body of the message.
            useragent:
              type: string
              description: >-
                The user agent string of the client that clicked
                the link.
    SpamReportEvent:
      description: >-
        Indicates that the recipient marked the email as spam using
        their email client.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: spamreport
    UnsubscribeEvent:
      description: >-
        Indicates that the recipient clicked the unsubscribe link
        and opted out of all future emails from the sender.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: unsubscribe
    GroupUnsubscribeEvent:
      description: >-
        Indicates that the recipient unsubscribed from a specific
        suppression group rather than all emails.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: group_unsubscribe
            asm_group_id:
              type: integer
              description: >-
                The ID of the suppression group the recipient
                unsubscribed from.
    GroupResubscribeEvent:
      description: >-
        Indicates that the recipient resubscribed to a specific
        suppression group after having previously unsubscribed.
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          properties:
            event:
              type: string
              const: group_resubscribe
            asm_group_id:
              type: integer
              description: >-
                The ID of the suppression group the recipient
                resubscribed to.