Class: Believe::Resources::Webhooks

Inherits:
Object
  • Object
show all
Defined in:
lib/believe/resources/webhooks.rb

Overview

Register webhook endpoints and trigger events for testing

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Webhooks

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Webhooks.

Parameters:



172
173
174
 
# File 'lib/believe/resources/webhooks.rb', line 172

def initialize(client:)
  @client = client
end

Instance Method Details

#create(url:, description: nil, event_types: nil, request_options: {}) ⇒ ::Believe::Models::WebhookCreateResponse

Register a new webhook endpoint to receive event notifications.

## Event Types

Available event types to subscribe to:

  • ‘match.completed` - Fired when a football match ends

  • ‘team_member.transferred` - Fired when a player/coach joins or leaves a team

If no event types are specified, the webhook will receive all event types.

## Webhook Signatures

All webhook deliveries include Standard Webhooks signature headers:

  • ‘webhook-id` - Unique message identifier

  • ‘webhook-timestamp` - Unix timestamp of when the webhook was sent

  • ‘webhook-signature` - HMAC-SHA256 signature in format `v1,base64_signature`

Store the returned ‘secret` securely - you’ll need it to verify webhook signatures.

Parameters:

Returns:

See Also:



42
43
44
45
46
47
48
49
50
51
 
# File 'lib/believe/resources/webhooks.rb', line 42

def create(params)
  parsed, options = ::Believe::WebhookCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "webhooks",
    body: parsed,
    model: ::Believe::Models::WebhookCreateResponse,
    options: options
  )
end

#delete(webhook_id, request_options: {}) ⇒ Hash{Symbol=>Object}

Unregister a webhook endpoint. It will no longer receive events.

Parameters:

Returns:

  • (Hash{Symbol=>Object})

See Also:



100
101
102
103
104
105
106
107
 
# File 'lib/believe/resources/webhooks.rb', line 100

def delete(webhook_id, params = {})
  @client.request(
    method: :delete,
    path: ["webhooks/%1$s", webhook_id],
    model: ::Believe::Internal::Type::HashOf[::Believe::Internal::Type::Unknown],
    options: params[:request_options]
  )
end

#list(request_options: {}) ⇒ Array<::Believe::Models::RegisteredWebhook>

Get a list of all registered webhook endpoints.

Parameters:

Returns:

See Also:



81
82
83
84
85
86
87
88
 
# File 'lib/believe/resources/webhooks.rb', line 81

def list(params = {})
  @client.request(
    method: :get,
    path: "webhooks",
    model: ::Believe::Internal::Type::ArrayOf[::Believe::RegisteredWebhook],
    options: params[:request_options]
  )
end

#retrieve(webhook_id, request_options: {}) ⇒ ::Believe::Models::RegisteredWebhook

Get details of a specific webhook endpoint.

Parameters:

Returns:

See Also:



63
64
65
66
67
68
69
70
 
# File 'lib/believe/resources/webhooks.rb', line 63

def retrieve(webhook_id, params = {})
  @client.request(
    method: :get,
    path: ["webhooks/%1$s", webhook_id],
    model: ::Believe::RegisteredWebhook,
    options: params[:request_options]
  )
end

#trigger_event(event_type:, payload: nil, request_options: {}) ⇒ ::Believe::Models::WebhookTriggerEventResponse

Trigger a webhook event and deliver it to all subscribed endpoints.

This endpoint is useful for testing your webhook integration. It will:

  1. Generate an event with the specified type and payload

  2. Find all webhooks subscribed to that event type

  3. Send a POST request to each webhook URL with signature headers

  4. Return the delivery results

## Event Payload

You can provide a custom payload, or leave it empty to use a sample payload.

## Webhook Signature Headers

Each webhook delivery includes:

  • ‘webhook-id` - Unique event identifier (e.g., `evt_abc123…`)

  • ‘webhook-timestamp` - Unix timestamp

  • ‘webhook-signature` - HMAC-SHA256 signature (`v1,base64`)

To verify signatures, compute:

“‘ signature = HMAC-SHA256(

key = base64_decode(secret_without_prefix),
message = "{timestamp}.{raw_json_payload}"

) “‘

Parameters:

Returns:

See Also:



150
151
152
153
154
155
156
157
158
159
 
# File 'lib/believe/resources/webhooks.rb', line 150

def trigger_event(params)
  parsed, options = ::Believe::WebhookTriggerEventParams.dump_request(params)
  @client.request(
    method: :post,
    path: "webhooks/trigger",
    body: parsed,
    model: ::Believe::Models::WebhookTriggerEventResponse,
    options: options
  )
end

#unwrap(payload) ⇒ ::Believe::Models::MatchCompletedWebhookEvent, ::Believe::Models::TeamMemberTransferredWebhookEvent

Parameters:

  • payload (String) —

    The raw webhook payload as a string

Returns:



164
165
166
167
 
# File 'lib/believe/resources/webhooks.rb', line 164

def unwrap(payload)
  parsed = JSON.parse(payload, symbolize_names: true)
  ::Believe::Internal::Type::Converter.coerce(::Believe::Models::UnwrapWebhookEvent, parsed)
end