Working with selling API events - AWS Partner Central
Complete the prerequisite to monitor eventsConfigure Amazon EventBridge to monitor eventsLearn more about selling API events

Working with selling API events

Events for the selling API provide real-time notifications about changes in the status or the details of opportunities. These events help keep your systems in sync with AWS Partner Central, and help ensure timely responses and updates.

Complete the prerequisite to monitor events

Users require the appropriate IAM permissions to access and manage events published by the Partner Central selling API. For more information about the available actions, resources, and condition keys for EventBridge, see Using IAM policy conditions in Amazon EventBridge in the Amazon EventBridge User Guide. One of the condition keys is events:detail-type, which can be used to scope permissions to specific event types.

The following example policy demonstrates how to customize and scope the permissions for the proposed events. The first statement, DenyPutRuleForAllPartnercentralSellingEvents, denies the ability to create rules for any events from the aws.partnercentral-selling source. This provides a baseline restriction. The second statement, AllowPutRuleForPartnercentralSellingEvents, allows the creation of rules, but only for events from the aws.partnercentral-selling source.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DenyPutRuleForAllPartnercentralSellingEvents",
            "Effect": "Deny",
            "Action": "events:PutRule",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "events:source": "aws.partnercentral-selling"
                }
            }
        },
        {
            "Sid": "AllowPutRuleForPartnercentralSellingEvents",
            "Effect": "Allow",
            "Action": "events:PutRule",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "events:source": "aws.partnercentral-selling"
                }
            }
        }
    ]
}

Configure Amazon EventBridge to monitor events

To monitor selling API events, you create an EventBridge rule that matches the events that you want to capture. You can use the AWS Management Console or the AWS SDKs to create and manage rules. The following sections explain how to create rules using both methods. Regardless of the method you use, you must create the rule in the US East (N. Virginia) us-east-1 Region.

AWS Management Console setup

To set up an EventBridge rule using the AWS Management Console, follow the steps in Creating rules that react to events in Amazon EventBridge in the Amazon EventBridge User Guide. When creating the rule, you must set the event bus to default, and create the rule in the US East (N. Virginia) us-east-1 Region.

Following is an example of an event rule:

{
    "source": ["aws.partnercentral-selling"],
    "detail": {
        "catalog": ["Sandbox"] 
    }
}

AWS SDK setup

You can use the AWS SDKs to create and manage EventBridge rules programmatically. For more information, see PutRule in the Amazon EventBridge API Reference.

The following example uses the AWS SDK for Python (Boto3):

import boto3

client = boto3.client('events')

response = client.put_rule(
    Name='MyOpportunityCreatedRule',
    EventPattern=
    '{  "region":["us-east-1"],
        "source": ["aws.partnercentral-selling"], 
        "detail-type": ["Opportunity Created"], 
        "detail": {"catalog": ["AWS"]}
    }',
    State='ENABLED'
)
print('Rule ARN:', response['RuleArn'])

Learn more about selling API events

The following sections describe the selling API event types, scenarios that trigger them, and event examples.

Event types

Following are the event types and their triggers.

  • Opportunity Created: Triggered when a new opportunity is created.

  • Opportunity Updated: Triggered when an opportunity (Opportunity or its corresponding AWS Opportunity Summary) is updated.

  • Engagement Invitation Created: Triggered when an AWS Referral invitation is created.

  • Engagement Invitation Accepted: Triggered when a partner accepts an AWS Engagement Invitation, confirming their interest in collaborating with AWS on the opportunity.

  • Engagement Invitation Rejected: Triggered when a partner rejects an AWS Engagement Invitation.

  • Engagement Invitation Expired: This event is triggered when a Partner rejects an EngagementInvitation. It notifies the sending and receiving partner that the invitation has expired.

  • Engagement Member Added: This event is triggered when a new member joins the Engagement after accepting an invitation. It notifies all current members of the Engagement about the new member being added to the Engagement.

  • Engagement Resource Snapshot Created: This event is triggered when the new revision of the Snapshot of the resources (such as opportunities) associated with an Engagement is created. It notifies all the current members of the Engagement about the changes to the associated resource Snapshot.

Event scenarios

The following table describes how events operate under different scenarios. The following assumptions are made for these scenarios:

  • AWS is also a partner in these scenarios.

  • ResourceSnapshotJob is configured correctly by the partner.

  • The fields updated on the opportunity are also on the opportunity template for Resource Snapshot.

Action by you as a partner Events received Participant type
You create an opportunity Opportunity Created
You use StartEngagementFromOpportunityTask to submit an opportunity Opportunity Updated, Engagement Resource Snapshot Created, Engagement Member Added, Engagement Invitation Created
AWS approves your submitted opportunity Engagement Invitation Accepted, Engagement Member Added, Opportunity Updated, Engagement Resource Snapshot Created
AWS rejects your submitted opportunity Engagement Invitation Rejected, Opportunity Updated, Engagement Resource Snapshot Created
You associate an AWS Marketplace offer with an opportunity Opportunity Updated
You associate a solution with an opportunity Opportunity Updated, Engagement Resource Snapshot Created
You update an opportunity Opportunity Updated, Engagement Resource Snapshot Created (Optional if ResourceSnapshotJob is set up and the field updates are on the template)
AWS updates your opportunity Opportunity Updated, Engagement Resource Snapshot Created
You invite another partner to an engagement Engagement Invitation Created Sender
Your invitation to join an engagement is accepted by a partner Engagement Invitation Accepted, Engagement Member Added Sender
Your invitation to join an engagement is rejected by a partner Engagement Invitation Rejected Sender
Your invitation to join an engagement is not acted on by a partner for 15 days Engagement Invitation Expired Sender
You receive an invitation from another partner to join an engagement Engagement Invitation Created Receiver
You accept the invitation from another partner to join an engagement via StartEngagementByAcceptingInvitationTask Engagement Invitation Accepted, Engagement Member Added, Opportunity Created, Opportunity Updated, Engagement Resource Snapshot Created Receiver
You reject the invitation to join an engagement from another partner Engagement Invitation Rejected Receiver
You do not act on invitation to join an engagement from another partner for 15 days Engagement Invitation Expired Receiver

Example events

The following sections provide examples of the events listed earlier in the previous section.

Opportunity Created

Partners use this event to:

  • Notify their users that a new Opportunity has been created.

  • Trigger automated workflows such as updating CRM systems or notifying sales teams about new opportunity creations.

The following example shows a typical Opportunity Created event.

{
    "version": "1",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "source": "aws.partnercentral-selling",
    "detail-type": "Opportunity Created",
    "time": "2023-04-16T15:23:45Z",
    "region": "us-east-1",
    "account": "123456789012",
    "detail": {
        "schemaVersion": "<version number>",
        "catalog": "<Sandbox | AWS>",
        "opportunity": {
            "identifier": "String"
        }
    }
}

Opportunity Updated

Partners use this event to:

  • Notify their users that an existing Opportunity has been updated.

  • Trigger automated workflows such as updating CRM systems or notifying sales teams.

The following example shows a typical Opportunity Updated event.

{
    "version": "1",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "source": "aws.partnercentral-selling",
    "detail-type": "Opportunity Updated",
    "time": "2023-04-16T15:23:45Z",
    "region": "us-east-1",
    "account": "123456789012",
    "detail": {
        "schemaVersion": "<version number>",
        "catalog": "<Sandbox | AWS>",
        "opportunity": {
             "identifier": "String"
        }
    }
}

Engagement Invitation Created

Partners use this event to:

  • Notify their users about the new EngagementInvitation they have received.

  • Trigger automated workflows to accept or reject the invitation, such as updating CRM systems or notifying sales teams.

The following example shows a typical Engagement Invitation Created event.

{
    "version": "0",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "detail-type": "Engagement Invitation Created",
    "source": "aws.partnercentral-selling",
    "account": "123456789012",
    "time": "2023-04-16T15:23:45Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo"
    ],
    "detail": {
      "catalog": "AWS",
      "engagementInvitation": {
        "arn": "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo",
        "id": "engi-v7p8z56whnauo",
        "engagementId": "eng-12345678901234",      
        "senderAccountId": "string",
        "receiverAccountId": "string",      
        "senderCompanyName": "string",
        "expirationDate": "string",
        "participantType": "Enum" //Sender/Receiver
      }
    }
}

Engagement Invitation Accepted

Partners use this event to:

  • Notify their users that the EngagementInvitation has been accepted.

  • Update their internal records to reflect the new partner in the Engagement.

  • Trigger automated workflows to synchronize data or notify other team members about the new Engagement member.

The following example shows a typical Engagement Invitation Accepted event.

{
    "version": "0",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "detail-type": "Engagement Invitation Accepted",
    "source": "aws.partnercentral-selling",
    "account": "123456789012",
    "time": "2023-04-16T15:23:45Z",
    "region": "us-east-1",
    "resources": ["arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo"],
    "detail": {
        "catalog": "AWS",
        "engagementInvitation": {
            "arn": "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo",
            "id": "engi-v7p8z56whnauo",
            "engagementId": "eng-12356whnauo",       
            "participantType": "Enum", //Sender/Receiver
            "senderAccountId": "string",
            "receiverAccountId": "string"
        }
    }
}

Engagement Invitation Rejected

Partners use this event to:

  • Notify their users that the EngagementInvitation has been rejected.

  • Update their internal records to reflect the rejected invitation.

  • Trigger any necessary workflows, such as notifying the sales team about the rejection.

The following example shows a typical Engagement Invitation Rejected event.

{
    "version": "0",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "detail-type": "Engagement Invitation Rejected",
    "source": "aws.partnercentral-selling",
    "account": "123456789012",
    "time": "2023-04-16T15:23:45Z",
    "region": "us-east-1",
    "resources": ["arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo"],
    "detail": {
        "catalog": "AWS",
        "engagementInvitation": {
            "arn": "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo",
            "id": "engi-v7p8z56whnauo",
            "engagementId": "eng-12356whnauo",
            "participantType": "Enum", //Sender/Receiver
            "senderAccountId": "string",
            "receiverAccountId": "string"       
        } 
    }
}

Engagement Invitation Expired

Partners use this event to:

  • Notify their users that the EngagementInvitation has expired and can no longer be acted upon.

  • Update their internal records to reflect the expired invitation.

  • Trigger any necessary workflows, such as notifying the sales team about the expired invitation.

The following example shows a typical Engagement Invitation Expired event.

{
    "version": "0",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "detail-type": "Engagement Invitation Expired",
    "source": "aws.partnercentral-selling",
    "account": "123456789012",
    "time": "2023-04-18T18:20:15Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo"
    ],
    "detail": {
      "catalog" : "AWS",    
      "engagementInvitation": {
        "arn": "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-v7p8z56whnauo",
        "id": "engi-v7p8z56whnauo",
        "engagementId": "eng-12356whnauo",        
        "participantType": "Enum", //Sender/Receiver
        "senderAccountId": "string",
        "receiverAccountId": "string"    
      }  
    }
}

Engagement Member Added

Partners use this event to:

  • Notify their users about the changes to the Engagement membership.

  • Update their internal records to reflect the new Engagement member.

  • Trigger any necessary workflows, such as notifying team members about the changes.

The following example shows a typical Engagement Member Added event.

{
    "version": "0",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "detail-type": "Engagement Member Added",
    "source": "aws.partnercentral-selling",
    "account": "123456789012",
    "time": "2023-04-16T15:23:45Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement/eng-v7p8z56whnauo"
    ],
    "detail": {
      "catalog" : "AWS",
      "engagement": {
        "id": "eng-v7p8z56whnauo"
      },
      "engagementMember": {
        "accountId": "string",
        "companyName": "string"
      }
    }
}

Engagement Resource Snapshot Created

Partners use this event to:

  • Notify their users about the changes to the Engagement resources.

  • Update their internal records to reflect the new Engagement resources.

  • Trigger any necessary workflows, such as updating opportunity or lead information in their CRM systems.

The following example shows a typical Engagement Resource Snapshot Created event.

{
    "version": "0",
    "id": "01234567-0123-0123-0123-0123456789ab",
    "detail-type": "Engagement Resource Snapshot Created",
    "source": "aws.partnercentral-selling",
    "account": "123456789012",
    "time": "2023-04-18T18:20:15Z",
    "region": "us-east-1",
    "resources": [
      "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement/eng-v7p8z56whnauo"
    ],
    "detail": {
      "catalog" : "AWS",
      "resourceSnapshot": {
        "arn": "arn:aws:partnercentral-selling:us-east-1::catalog/AWS/engagement/eng-v7p8z56whnauo/resource/Opportunity/o-12312/template/temp-name/snapshot/snapshot-19232",
        "engagementId": "eng-v7p8z56whnauo",
        "resourceType": "Opportunity",      
        "resourceId" : "O123211231",
        "createdBy": "123123123123"
      }
    }
}