Webhook Configuration

To receive the webhook events, you need to do the following:

• Create an endpoint to receive events that are published to a webhook topic.
• Specify the endpoint as a webhook subscription's destination.
• If your extension needs to stay in sync with Fynd Platform, then always replace your local copy of any store data with the webhook payload.

Step 1: How to register for webhook events?

Webhook events can be helpful to handle tasks when certain events occur on the platform. You can subscribe to such events by passing webhook_config in setupFdk function in FDK Extension Library

Javascript

/app/fdk/index.js

let fdkExtension = setupFdk({
  api_key: "<API_KEY>",
  api_secret: "<API_SECRET>",
  callbacks: extensionHandler,
  storage: new RedisStorage(redis, "example_app"),
  access_mode: "offline",
  cluster: "https://api.fynd.com",
  webhook_config: {
    api_path: "/api/v1/webhooks", // required
    notification_email: "test@abc.com", // required
    subscribe_on_install: false, // optional. default `true`
    subscribed_saleschannel: 'specific', // optional. default all
    event_map: { // required
      'company/location/update': {
        version: '1',
        handler: handleLocationEvent
      },
      'company/product/create': {
        version: '1',
        handler: handleProductEvent
      },
      'application/coupon/create': {
        version: '1',
        handler: handleCouponCreate
      }
    }
  },
});

Python

app/fdk/fdk.py

fdk_extension = setup_fdk({
  "api_key": "<api_key>",
  "api_secret": "<api_secret>",
  "callbacks": extension_handler,
  "storage": RedisStorage(redis_connection, "example_app"),
  "access_mode": "offline",
  "cluster": "https://api.fynd.com",
  "webhook_config": {
    "api_path": "/api/v1/webhooks", # required
    "notification_email": "test2@abc.com",  # required
    "subscribe_on_install": False, # optional. default `True`
    "subscribed_saleschannel": "specific",  # optional. default `all`
    "event_map": {  # required
      'company/location/update': {
        "version": '1',
        "handler": handle_location_event
      },
      "company/product/create": {
        "version": '1',
        "handler": handle_product_event
      },
      "application/coupon/create": {
        "version": '1',
        "handler": handle_coupon_create
      }
    }
  }
})

Java

/src/main/resources/application.yml

ext :
  api_key : '<api_key>'
  api_secret : '<api_secret>'
  scopes: 'company/saleschannel'
  access_mode : 'offline'
  cluster: "https://api.fynd.com"
  webhook:
    api_path: "/api/v1/webhooks" # required
    notification_email: "test2@abc.com" # required
    subscribe_on_install: false # optional. default `true`
    subscribed_saleschannel: 'all' 
    event_map: # required
      -
        name: 'location/update'
        handler: handleLocationEvent
        category: 'company'
        version: 1
      -
        name: 'product/create'
        handler: handleProductEvent
        category: 'company'
        version: 1
      -
        name: 'coupon/create'
        handler: handleCouponCreate
        category: 'application'
        version: 1

By default, all webhook events all subscribed for all companies whenever they are installed. To disable this behavior set subscribe_on_install to false. If subscribe_on_install is set to false, you need to manually enable webhook event subscription by calling syncEvents method of webhookRegistry.

note

You can derive webhook topics to be passed in event_map for required events from event payload dictionary as follows

event_map: { // required
      '<category>/<event name>/<type>': {
        version: '1',
        handler: handleLocationEvent
      },
}

Step 2: Create a api endpoint for webhook to listen

There should be view on given API path to receive webhook calls. It should be POST API path. API view should call processWebhook method of webhookRegistry object available under fdkClient here. Here processWebhook will do payload validation with signature and calls individual handlers for event passed with webhook config.

Javascript

app.post('/api/v1/webhooks', async (req, res, next) => {
  try { 
    await fdkExtension.webhookRegistry.processWebhook(req); 
    return res.status(200).json({"success": true}); 
  } catch(err) { 
    logger.error(err); 
    return res.status(400).json({"success": false}); 
  } 
});

Python

async def webhook_handler(request):
    try:
        await fdk_extension.webhook_registry.process_webhook(request)
        return response.json({"success": True}, 200)
    except Exception as e:
        logger.exception(e)
        return response.json({"success": False}, 400)

# register route
app.add_route(webhook_handler, "/api/v1/webhooks", methods=["POST"])

Java

@CrossOrigin(origins = "*")
@RestController
@RequestMapping()
@Slf4j
public class WebhookController {

    @Autowired
    WebhookService webhookService;

    private static final Logger log = LoggerFactory.getLogger(SampleEventHandler.class);

    @PostMapping(path = "/api/v1/webhooks")
    public ResponseEntity<Object> receiveWebhookEvents(HttpServletRequest httpServletRequest) {
        try {
            webhookService.processWebhook(httpServletRequest);
            return new ResponseEntity<>(Collections.singletonMap("success", true), HttpStatus.OK);
        } catch (Exception e) {
            log.error("Exception occurred", e);
            return new ResponseEntity<>(Collections.singletonMap("success", false), HttpStatus.BAD_REQUEST);
        }
    }
}

Step 3: Configure your webhook settings

Setting subscribed_saleschannel as "specific" means, you will have to manually subscribe to sales channel/website level events for individual sales channels.

The default value here is "all" and the event will be subscribed for all sales channels. For enabling events manually use function enableSalesChannelWebhook. To disable receiving events for a sales channel use the function disableSalesChannelWebhook.

How webhook registry subscribes to webhooks on Fynd Platform?

After webhook config is passed to setupFdk whenever an extension is launched to any of companies where extension is installed or to be installed, webhook config data is used to create webhook subscriber on Fynd Platform for that company. Any update to webhook config will not automatically update subscriber data on Fynd Platform for a company until the extension is opened at least once after the update. Another way to update the webhook config manually for a company is to call the syncEvents function of webhookRegistery.