Events and Webhooks
Most operations and status changes in our resources are accompanied by an event indicating its occurrence. We list below some important examples. Note that every event has a type representing what happened, and it always starts with a com.gigs. prefix:
| Type | Description |
|---|---|
com.gigs.subscription.activated | Indicates a created subscription has been activated by the network provider and is ready to use. |
com.gigs.subscription.renewed | Indicates a subscription has been renewed. |
com.gigs.porting.requested | Created when a request for porting a number is sent to the network provider. |
com.gigs.device.updated | Triggered whenever there is any change to a device resource. |
com.gigs.subscriptionChange.applied | A scheduled requested change to a subscription has been successfully applied. |
com.gigs.usageThreshold.exceeded | Indicates some threshold was exceeded in the subscription allowance. For example, it could indicate that 50% of the data limit for a specific subscription has been used. |
All events have payloads with relevant details in a data field. In addition, the *.updated events also have a previousData field with previous values
from all fields that changed as part of the update.
Below we will explain how you can access these events by using the Gigs dashboard, or configuring webhooks.
List of events
A full list of events and what payloads they contain can be found in the Gigs Events section of our documentation.
Dashboard
All events can be accessed in the events section of Gigs dashboard, where they can be filtered by resource and type. In addition, most resource pages have a "Recent Activity" section showing the latest events related to it. That's not just events that impacted the resource directly, but also ones that affected linked resources.
For instance, in a subscription page, it's possible to see directly related events, like subscription renewals, but it's also possible to see:
- successful payments (for projects using Gigs payments);
- changes to the linked SIM and device;
- usage thresholds being reached;
- creation of subscription add-ons, such as when a top-up is added to the subscription.
Whether in the full event list, or in the "Recent Activity" section, by clicking on the event it's possible to see its full payload.
Webhooks
To be able to be notified of an event, as soon as it happens, you can also configure a webhook endpoint in the developers section of the Gigs dashboard.
The events sent are the same ones visible in Gigs dashboard, and documented in the Gigs Events section of our API documentation.
Adding an endpoint
To configure a webhook endpoint, you should click on the "Manage Webhooks" link, which opens a specific dashboard tailored to this feature. This is managed by a third-party provider called Svix.
Once there, you can add an endpoint and set the URL where the requests should be sent to. You can also select which events you'd like to receive on this endpoint.
It's important that the server which receives the webhook requests verifies them. The reasoning and details on how the verification should be done can be found here. The verification can be done either through one of the Svix-provided client applications, or manually, by verifying the request headers (webhook-id, webhook-signature, and webhook-timestamp), as detailed here.