📨Asynchronous webhooks

Architecture

Asynchronous webhooks can be used for reacting to the events emitted by Magami. The worker instance will send the event payload via the chosen protocol. Your app should acknowledge receiving that payload. The result of the app operations is not sent back to the Magami. If you need to send data back to the user (for example, overriding draw prize/reward rules), you should use a synchronous webhook.

Examples of the use cases

• Sending a notification about a claimed coupon to the company chat;

• Updating Elasticsearch or Algolia indexes after an end-user has won a prize draw; and

• Many more.

Permissions

No permission needed yet.

Webhook protocol

Asynchronous webhooks currently only support HTTP(S) protocol.

HTTP(S)

Webhook payloads are sent in POST requests.

If a successful response has not been received in the case of temporary service unavailability, it will retry its request after a delay in time.

While HTTPS webhooks are a familiar concept and may seem easy to implement, ensure your endpoint can handle the same level of concurrency that you expect from the monitored events. Magami will do its best to deliver webhooks in real time, which could mean more traffic than your servers can handle. Because of this and the possibility of losing events when the destination server is down, so be careful.

Headers

During HTTPS requests there are several headers included:

• Magami-Event - defines an event which is assigned to the webhook

• Magami-Signature - defines a signature to indicate that the request is verifiable

Webhook payload object common properties

Each webhook event payload also contains properties unique to the event. You can find the unique properties in the individual event type sections.

Payload signature

Magami calculates a payload signature under Magami-Signature which was set with HMAC SHA-256 header based on the API key as the secret key and the payload.

Configuration

You can add your webhook either in the Integrations section inside campaign detail page or Integrations page inside your admin dashboard. Make sure to select events in the Actions section which suit your needs before you save your webhook information.

Available webhook events

Webhooks can be used to receive data from Magami when particular events happen. The available events are:

Name	Description	Payload
coupon_validated	A coupon is being validated	See reference here
redemption_created	A user/participant has filled the form, a coupon might also be claimed	See reference here
redemption_drawn	A user/participant is starting the prize draw	See reference here
redemption_won_prize	A user/participant is awarded a prize from the draw	See reference here
user_created	A user is created	See reference here
user_updated	A user is updated	See reference here
user_deleted	A user is deleted	See reference here
campaign_created	A campaign is created	See reference here
campaign_updated	A campaign is updated	See reference here
campaign_deleted	A campaign is deleted	See reference here
coupon_set_created	A coupon set is created	See reference here
coupon_set_updated	A coupon set is updated	See reference here
coupon_set_deleted	A coupon set is deleted	See reference here
coupons_generated	Coupon(s) has been generated	See reference here
coupons_imported	Coupon(s) has been imported	See reference here
coupon_updated	A coupon is updated	See reference here
coupon_deleted	A coupon is deleted	See reference here