Module: Pago::V2026_04::Webhooks

Defined in:
lib/pago/v2026_04/webhooks.rb,
sig/pago/v2026_04/generated.rbs

Overview

Webhook verification and deserialization for the 2026-04 API.

Examples:

Rack / Rails

event = Pago::Webhooks.validate_event(
  body: request.body.read,
  headers: request.headers,
  secret: ENV.fetch("PAGO_WEBHOOK_SECRET")
)
case event
when Pago::Models::WebhookOrderPaidPayload then fulfill(event.data)
end

Class Method Summary collapse

Class Method Details

.event_types ⇒ Hash{String => Class}

Returns event type to payload model.

Returns:

  • (Hash{String => Class}) —

    event type to payload model.



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/pago/v2026_04/webhooks.rb', line 18

def self.event_types
  @event_types ||= {
    "benefit.created" => Models::WebhookBenefitCreatedPayload,
    "benefit.updated" => Models::WebhookBenefitUpdatedPayload,
    "benefit_grant.created" => Models::WebhookBenefitGrantCreatedPayload,
    "benefit_grant.cycled" => Models::WebhookBenefitGrantCycledPayload,
    "benefit_grant.revoked" => Models::WebhookBenefitGrantRevokedPayload,
    "benefit_grant.updated" => Models::WebhookBenefitGrantUpdatedPayload,
    "checkout.created" => Models::WebhookCheckoutCreatedPayload,
    "checkout.expired" => Models::WebhookCheckoutExpiredPayload,
    "checkout.updated" => Models::WebhookCheckoutUpdatedPayload,
    "customer.created" => Models::WebhookCustomerCreatedPayload,
    "customer.deleted" => Models::WebhookCustomerDeletedPayload,
    "customer.state_changed" => Models::WebhookCustomerStateChangedPayload,
    "customer.updated" => Models::WebhookCustomerUpdatedPayload,
    "customer_seat.assigned" => Models::WebhookCustomerSeatAssignedPayload,
    "customer_seat.claimed" => Models::WebhookCustomerSeatClaimedPayload,
    "customer_seat.revoked" => Models::WebhookCustomerSeatRevokedPayload,
    "member.created" => Models::WebhookMemberCreatedPayload,
    "member.deleted" => Models::WebhookMemberDeletedPayload,
    "member.updated" => Models::WebhookMemberUpdatedPayload,
    "order.created" => Models::WebhookOrderCreatedPayload,
    "order.paid" => Models::WebhookOrderPaidPayload,
    "order.refunded" => Models::WebhookOrderRefundedPayload,
    "order.updated" => Models::WebhookOrderUpdatedPayload,
    "organization.updated" => Models::WebhookOrganizationUpdatedPayload,
    "product.created" => Models::WebhookProductCreatedPayload,
    "product.updated" => Models::WebhookProductUpdatedPayload,
    "refund.created" => Models::WebhookRefundCreatedPayload,
    "refund.updated" => Models::WebhookRefundUpdatedPayload,
    "subscription.active" => Models::WebhookSubscriptionActivePayload,
    "subscription.canceled" => Models::WebhookSubscriptionCanceledPayload,
    "subscription.created" => Models::WebhookSubscriptionCreatedPayload,
    "subscription.past_due" => Models::WebhookSubscriptionPastDuePayload,
    "subscription.paused" => Models::WebhookSubscriptionPausedPayload,
    "subscription.resumed" => Models::WebhookSubscriptionResumedPayload,
    "subscription.revoked" => Models::WebhookSubscriptionRevokedPayload,
    "subscription.uncanceled" => Models::WebhookSubscriptionUncanceledPayload,
    "subscription.updated" => Models::WebhookSubscriptionUpdatedPayload
  }.freeze
end

.known_event_types ⇒ Array<String>

Returns every event type known to this SDK version.

Returns:

  • (Array<String>) —

    every event type known to this SDK version.



61
 
# File 'lib/pago/v2026_04/webhooks.rb', line 61

def self.known_event_types = event_types.keys

.validate_event(body:, headers:, secret:) ⇒ Pago::Model

Verify a raw webhook request and deserialize its payload.

Parameters:

  • body (String) —

    the raw request body, exactly as received.

  • headers (Hash{String => String}) —

    the request headers.

  • secret (String) —

    the endpoint secret, in whsec_<base64> form.

  • body: (String)
  • headers: (Hash[untyped, untyped])
  • secret: (String)

Returns:

Raises:



73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/pago/v2026_04/webhooks.rb', line 73

def self.validate_event(body:, headers:, secret:)
  data = ::Pago::WebhookVerifier.verify(body: body, headers: headers, secret: secret)
  event_type = data.is_a?(Hash) ? data["type"] : nil
  payload_class = event_types[event_type]
  raise ::Pago::WebhookUnknownTypeError, event_type if payload_class.nil?

  payload = payload_class.from_json(data)
  raise ::Pago::WebhookError, "Failed to parse webhook payload" if payload.nil?

  payload
end